Swagger 快速上手

 

导语：

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

 

建议先直接导文章末尾，看一下Swagger是个什么东西

 

1.下载依赖包pom.xml

  <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2.写配置类

package com.ybzn.config;

import com.ybzn.swagger.HelloController;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.autoconfigure.thymeleaf.ThymeleafAutoConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.HandlerMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

/**
 * @EnableSwagger2开启Swagger2，如果没有这个是无法启动的
 * @author Hugo
 * @time 2020/4/8
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket docket(){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors ，扫描配置接口的方式
                //basePackage: 扫描需要的包
                // any(): 扫描全部
                // none(): 不扫描，包过滤
                // withMethodAnnotation : 扫描方法上面的注解
                // withClassAnnotation : 扫描类上面的注解
                .apis(RequestHandlerSelectors.basePackage("com.ybzn.swagger"))
                //paths() 过滤什么路径,只有hugo下面的才可以访问
                .paths(PathSelectors.ant("/hugo/**"))
                .build();
    }

    private ApiInfo apiInfo(){
        //作者信息
        Contact DEFAULT_CONTACT = new Contact("Hugo", "www.baidu.com", "1192179830@qq.com");

        return  new ApiInfo("LMJ 的API 测试文档", "我的API接口测试文档", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

3.撰写控制类，这样就可以直接扫码到了

package com.ybzn.swagger;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.websocket.server.PathParam;

/**
 * @author Hugo
 * @time 2020/4/8
 */
@RestController
@RequestMapping("/hugo")
public class HelloController {

    @GetMapping("/index")
    public String helloSwagger(){
        return "Hello";
    }

    @GetMapping("/test1")
    public String test1(){
        return "Hello111";
    }
    @PostMapping("/test2")
    @ApiOperation("get控制类，带参数的")
    public String wsaw(@PathParam("username") String username){
        return "Hello222"+username;
    }

    /**
     * 只要我们的接口中，返回值存在实体类，
     * 就会被扫描到Swagger上面来
     * @return
     */
    @PostMapping(value = "/user")
    public User user(User user){
        User user1 = new User();
        user1.username=user.username;
        user1.password=user.password;
        return  user1;
    }


}

4.实体类可以加API注释

/**
 * @author Hugo
 * @time 2020/4/8
 */
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

5.访问http://localhost:8080/swagger-ui.html页面

 

 

 

 下拉就可以看到测试结果。