swagger2 使用方法

Swagger为我们提供了一套通过代码和注释自动生成文档的方法，这一点对于保证API文档的及时性将有很大的帮助。可以帮助我们设计、构建、记录以及使用Rest api

• 引入依赖

        <!-- 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>

• 将swagger配置注入spring

/**
 * @Configuration
 * 首先声明是配置文件类
 * @EnableSwagger2
 * 开启swagger功能
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 使用swagger需要创建一个摘要。Docket
     * 摘要参数如下：
     * 文档的类型：DocumentationType.SWAGGER_2
     * 文档通过一系列的选择器组成：api path
     * select() 设置apis和paths()
     * apis 查找生成哪些controller的接口
     *      获取所有：RequestHandlerSelectors.any()
     *      如果要获取指定的一个包：RequestHandlerSelectors.basePackage("com.fanfan.controller")
     * path 在查找出来的接口中进行筛选
     * @return
     */
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.fanfan.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    /**
     * 自定义文档的介绍
     * 通过apiInfBuilder创建apiInfo
     * 参数可以设置 title description version 等等
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("spring-boot-swagger")
                .description("这是一个简单的demo")
                .version("1.0")
                .build();
    }
}

• 浏览器打开
  • http://localhost:8090/swagger-ui.html

测试一下：

controller：

/**
 * @Api 声明一系列接口的功能，放在controller之上
 * @ApiOperation 声明具体接口的功能 放在controller方法之上
 */
@RestController
@Api(tags = "测试相关的接口", description = "玩一玩测试CURD")
public class TestController {

    @GetMapping("/test")
    @ApiOperation("第一个测试接口")
    public void test(){
        System.out.println(1);
    }

    /**
     * @ApiIgnore 不显示此接口
     * @param test
     * @return
     */
    @PostMapping("/add")
    @ApiOperation("测试名字")
    public String add(Test test){
        return "add";
    }

    @ApiOperation("删除嘉宾接口")
    @ApiImplicitParam(name = "id", value = "测试id")
    @PostMapping("/delete")
    public String delete(Long id){
        return "delete";
    }
}

bean文件：

/**
 * @ApiModel("嘉宾") 声明实例
 * @ApiModelProperty("名字") 声明实例属性的名字，用于接口的参数显示
 */
@Data
@AllArgsConstructor
@ApiModel("测试实例")
public class Test {
    @ApiModelProperty("名字")
    private String name;
    @ApiModelProperty("角色")
    private String role;
}