接口文档"/>
使用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);}
更多推荐
使用Swagger2生成接口文档
发布评论