Swagger使用小记

Swagger是一种框架，用于自动生成Restfull API的文档，而不用开发者自己编写文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

以下以SpringBoot 2.0.1中整合Swagger2.8.0为例.

1、Maven：

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

2、建立Swagger配置类

@Configuration // 表明它是一个配置类
@EnableSwagger2 // 开启swagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.sensetime.sensestudy.web"))// 指定扫描的包，其下Controller会生成文档
                // .paths(regex("/product.*"))
                .paths(PathSelectors.any()).build()//
                .apiInfo(metaData());// 指定页面的基本信息

    }

    private ApiInfo metaData() {// 设置页面的基础信息
        return new ApiInfoBuilder().title("Sensestudy Server API")
                .description(""Spring Boot REST API for Sensestudy"").version("1.0.0")
                .license("Apache License Version 2.0").licenseUrl("https://www.apache.org/licenses/LICENSE-2.0"")
                .contact(
                        new Contact("John Thompson", "https://springframework.guru/about/", "john@springfrmework.guru"))
                .build();
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {// API文档页面相关资源作为静态资源，以防止被拦截处理
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3、Swagger使用：相关注解

　swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数

4、访问

http://localhost:8080/swagger-ui.html：（UI风格）

http://localhost:8080/v2/api-docs：（API风格）

参考资料：

1、SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2

2、https://blog.csdn.net/hu_zhiting/article/details/80462110