使用Swagger2生成接口文档

1 Swagger2

程序员儿在开发Controller时使用特定注解对api接口就行说明标注，Swagger2可自动读取API结构信息并自动构建漂亮的可交互式（对接口进行简单测试）的API文档。省去了写接口文档的麻烦。

2 基础使用

2.1 添加依赖

可在maven查询Springfox Swagger2的相关依赖，我查了2.9.2用的最多，所以就用这个版本。

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

2.2 添加配置类

@Configuration
@EnableSwagger2
public class Swagger2Config {
    public static final String SWAGGER2_SCAN_BASE_PACKAGE = "com.example.demo";
    public static final String VERSION = "1.0.0";
    @Bean
    public Docket createApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER2_SCAN_BASE_PACKAGE))
                 // 根据url路径过滤进入文档的请求
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("")
                .version(VERSION)
                .build();
    }
}

 

2.3 接口配置

2.3.1 @Api

对类修饰，说明该类的作用

• tags：说明该类的作用(常用)
• value：也是设置标签的方法，但仅在tags为空时有效
• produces：指定返回值类型和返回值的字符编码
• consumes:指定处理请求的提交内容类型(content-Type)
• protocols:指定协议

@Api(tags = "公式模块参数API接口")
public class ParamController {}

2.3.2 @ApiOperation

对方法修饰，说明一个方法（api接口）的作用。

• value：对应摘要，方法的简要说明
• notes：方法的详细描述
• tags：标签字段，非空会覆盖value
• .....

@ApiOperation(value="删除指定参数",notes="需传入被删除参数的参数id")

2.3.3 @ApiImplicitParam

对方法修饰，指定一个参数的配置说明

@ApiImplicitParam(name="id",value="参数id",required=true,paramType="form")

2.3.4 @ApiImplicitParams

对方法修饰，指定一组参数的配置说明

@ApiImplicitParams({
    @ApiImplicitParam(name="id",value="参数id",required=true,paramType="form"),
    @ApiImplicitParam(name="date",value="日期",required=true,paramType="form")
})

2.3.5 @ApiParam

用在方法或参数上，为操作参数添加元数据

2.3.6 @ApiModel

对实体类修饰，对类的说明

2.3.7 @ApiModelProperty

对实体类方法、字段修饰，表示实体类属性的说明或者数据操作更改

@ApiModel(description= "响应数据")
public class Reponse implements Serializable{
    @ApiModelProperty(value = "返回代码")
    private int code =true;
    @ApiModelProperty(value = "返回信息")
    private String msg;
    /* getter/setter */
    }

2.3.8 @ApiResponse

用在方法上，描述操作可能的响应

2.3.9 @ApiResponses

用在方法上，描述操作可能的响应组

 

2.4 完成

配置完成后，运行项目，访问 http://127.0.0.1:8080/swagger-ui.html ,当然你可能会出现404 not found的问题，那么就可以直接翻到第4章。

3 常见坑

3.1 启动后404

这个问题最常见的原因是继承WebMvcConfigurationSupport类进行跨域设置。在跨域配置类中重写addResourceHandlers方法即可。

@Configuration
public class WebApiConfig extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "OPTIONS", "DELETE", "PATCH")
                .allowCredentials(true).maxAge(3600);
    }