使用Swagger2生成接口文档

接口文档"/>

使用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";@Beanpublic 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 {@Overridepublic 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);}@Overridepublic void addCorsMappings(CorsRegistry registry) {registry.addMapping("/**").allowedOrigins("*").allowedMethods("GET", "POST", "PUT", "OPTIONS", "DELETE", "PATCH").allowCredentials(true).maxAge(3600);}