Swagger快速上手和使用

Swagger简介

• 号称世界上最流行的API框架
• Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新
• 直接运行，在线测试API
• 官网：https://swagger.io/

SpringBoot集成Swagger

1. 导jar包

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

2. 开启swagger

@Configuration//配置类@EnableSwagger2// 开启Swagger2的自动配置publicclassSwaggerConfig{}

3. 访问路径
   http://localhost:8080/swagger-ui.html
4. swagger界面
   

Swagger配置

1. 配置文档信息

@Configuration//配置类@EnableSwagger2// 开启Swagger2的自动配置publicclassSwaggerConfig{//配置文档信息@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.SWAGGER_2)//配置文档信息，swagger信息.apiInfo(apiInfo());//配置扫描接口信息，只会扫描controller的方法，生成接口文档，普通的类的方法不会扫描.select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.kuang.swagger"))// 配置如何通过path过滤,即这里只扫描请求以/kuang开头的接口.paths(PathSelectors.ant("/kuang/**"))//一般PathSelectors.any() s扫描所有接口，也可以不配置.paths()方法；.build();}}//配置文档信息privateApiInfoapiInfo(){Contactcontact=newContact("联系人名字","http://xxx.xxx.com/联系人访问链接","联系人邮箱");returnnewApiInfo("Swagger学习",// 标题"学习演示如何配置Swagger",// 描述"v1.0",// 版本"http://terms.service.url/组织链接",// 组织链接contact,// 联系人信息"Apach 2.0 许可",// 许可"许可链接",// 许可连接newArrayList<>()// 扩展);}

常用注解

• @Api(tags = “xxx模块说明”)

  作用在controller类上

• @ApiOperation(“xxx接口说明”)

  作用在controller接口方法上

• @ApiModel(“xxxPOJO说明”)

  作用在模型类上：如VO（返回值实体类）、DTO（参数实体类）

• @ApiModelProperty(value = “xxx属性说明”,hidden = true)

  作用在模型类属性上，hidden设置为true可以隐藏该属性

• @ApiParam(“xxx参数说明”)

  作用在controller接口方法参数上

注意，尽量不要使用注解name属性，别误导前端发错参数名