springboot整合swagger2之最佳实践

本文主要是介绍springboot整合swagger2之最佳实践，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

来源:https://blog.lqdev.cn/2018/07/21/springboot/chapter-ten/

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。

一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

SpringBoot集成

<!--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>

编写配置文件(SwaggerConfig.java)

@EnableSwagger2
@Configuration
public class SwaggerConfig {//是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置@Value(value = "${swagger.enabled}")Boolean swaggerEnabled;@Beanpublic 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	用在返回对象类上