springboot整合swagger2
springboot整合swagger2
Swagger
是一款RESTful
接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架,用于生成、描述、调用和可视化RESTful
风格的Web服务,加上swagger-ui
,可以有很好的呈现。
SpringBoot集成
- pom
<!--swagger -->
<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>
- 编写配置文件(Swagger2Config.java)
@EnableSwagger2
@Configuration
public class SwaggerConfig {
//是否开启swagger,正式环境一般是需要关闭的,可根据springboot的多环境配置进行设置
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
// 是否开启
.enable(swaggerEnabled).select()
// 扫描的路径包
.apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
// 指定路径处理PathSelectors.any()代表所有的路径
.paths(PathSelectors.any()).build().pathMapping("/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot-Swagger2集成和使用-demo示例")
.description("oKong | 趔趄的猿")
// 作者信息
.contact(new Contact("oKong", "https://blog.lqdev.cn/", "499452441@qq.com"))
.version("1.0.0")
.build();
}
}
设置注解
-
controller
- 类:@Api(value = "预订业务逻辑接口", description = "预订业务逻辑接口",tags="用户API")
- 方法:@ApiOperation(value = "保存预订数据", response = 本类.class)
- 路径参数/{id}:@ApiImplicitParam(name="id",value="查询ID",required=true)
- 普通参数:@ApiParam(name = "id", value = "预订食品信息id", required = true)
-
entity
- 类名:@ApiModel(value = "记账凭证详情", description = "记账凭证详情")
- 类属性:@ApiModelProperty(name = "id", value = "记账凭证详情ID",dataType="String",example="1020332806740959233" )
访问:http://127.0.0.1:8080/swagger-ui.html
Swagger常用属性说明
作用范围 | API | 使用位置 |
---|---|---|
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
协议集描述 | @Api | 用于controller类上 |
协议描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
常用的注解@Api
、@ApiOperation
、@ApiModel
、@ApiModelProperty
示例中有进行标注,对于其他注解,大家可自动谷歌,毕竟常用的就这几个了。有了swagger之后,原本一些post请求需要postman这样的调试工具来进行发起,而现在直接在页面上就可以进行调试了,是不是很爽!对于服务的调用者而已,有了这份api文档也是一目了然,不需要和后端多少沟通成本,按着api说明进行前端开发即可。