使用Swagger2生成API文档

Swagger2是一个开源软件框架，由大型工具生态系统支持，可帮助开发人员设计，构建，记录和使用Restful Web服务。

这是“维基百科”上对于Swagger2的一个介绍，可见Swagger2是属于第三方框架，对标的是Restful风格的API，使用Swagger2生成API文档，避免了传统手工记录的繁琐，也便于保存、整理、查阅和调试API接口。

在SpringBoot项目中引入Swagger2：

• pom.xml引入对应的依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

• 增加SwaggerConfig.java配置文件，配置项目启动时同时加载swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //接口对应包下的类，生成API文档
            .apis(RequestHandlerSelectors.basePackage("io.swagger.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("可读小说")
            .description("后台管理系统API文档")
            .termsOfServiceUrl("https://swagger.io/")
            .version("1.0.1")
            .build();
    }
}

同时利用Swagger2提供的注解对接口进行说明，通过访问http://localhost:8080/swagger-ui.html便可获取到相关API文档。

注解的使用（demo）

@Api("小说信息接口")
@RestController
@RequestMapping("/info")
public class InfoController {

    @ApiOperation("添加小说信息")
    @PutMapping("/add")
    private String addInfo(){
        return "success";
    }

    @ApiOperation("获取小说信息")
    @GetMapping("/{id}")
    private String getInfo( @ApiParam("小说id") @PathVariable("id")int id){
        return "info" + id;
    }
}

运行结果

最后再说说Swagger2的常用注解：

• @Api：用于类，表示标识这个类是swagger的资源
• @ApiOperation：用于方法，表示一个http请求的操作
• @ApiParam：用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）
• @ApiModel：用于类，表示对数据模型进行说明，用于参数用实体类接收
• @ApiModelProperty：用于方法，字段，表示对model属性的说明
• @ApiIgnore：用于类，方法，方法参数，对应的将不会被显示到文档里
• @ApiImplicitParam：用于方法，作用于非对象参数集
• @ApiImplicitParams：用于方法，包含多个 @ApiImplicitParam