本文共 3902 字，大约阅读时间需要 13 分钟。

一、概述

Swagger是一个接口文档工具，提供接口文档的自动生成和测试的工具。

致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。

它能够自动生成接口文档和客户端服务端代码，做到代码和接口的一致性，让我们花精力去修改接口文档。

二、入门案例

先把例子跑起来，再回头理解代码。

使用环境或技术：

• SpringBoot 2.4.5

1、maven导入依赖文件

   
       
    
     io.springfox
        
    
     springfox-swagger2
        
    
     2.9.2
    
   
   
       
    
     io.springfox
        
    
     springfox-swagger-ui
        
    
     2.9.2
    
   

2、写一个配置类（代码有注释说明）

/** * @author Hacah * @date 2021/5/12 11:00 */@Configuration@EnableSwagger2public class SwaggerConfig {
       @Bean    public Docket productApi() {
           return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo())                // 配置是否启动swagger,默认为true                .enable(true)                .select()                /**                 * apis():指定扫描的接口                 *  RequestHandlerSelectors:配置要扫描接口的方式                 *       basePackage:指定要扫描的包                 *       any:扫面全部                 *       none:不扫描                 *       withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)                 *       withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)                 */                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                /**                 * paths():过滤路径                 *  PathSelectors:配置过滤的路径                 *      any:过滤全部路径                 *      none:不过滤路径                 *      ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配                 *      regex:过滤指定路径:按照String的matches方法进行匹配                 */                .paths(PathSelectors.any())                .build();    }    private ApiInfo apiInfo() {
           return new ApiInfoBuilder()            .title("swagger和springBoot整合")            .description("swagger和SpringBoot整合")            .version("1.0.0.0").build();    }}

3、编写一个RestController，添加@ApiOperation注解

@ApiOperation(value = "hello")@RequestMapping("/hello")public String hello() {
       return "Hello World!";}

4、启动项目，打开地址localhost:8080/swagger-ui.html

解释：

• @ApiOperatio：作用方法上，说明该接口干嘛的。

• .select().apis.paths.build是组合使用的

三、常用注解或操作

1、文档分组

• 设置组名，在创建Docket时，执行groupName操作

return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())//配置Swagger信息            .groupName("zsr")    		...

• 创建多个Docket对象，指定组名就有多个组了

2、实体类注解

• @ApiModel为类添加注释，说明是什么类。
• @ApiModelProperty为类属性添加注释，说明是什么属性。

例如：

@ApiModel(value = "条件类", description = "存储请求过来的查询条件和内容和分页信息")@Datapublic class PageVO {
       @ApiModelProperty(value = "查询条件")    private List
   
     queryCondition;    @ApiModelProperty(value = "查询内容")    private String queryContent;    @ApiModelProperty(value = "页号")    private Integer pageNum = 1;    @ApiModelProperty(value = "每页显示数量")    private Integer pageSize = 20;
   

结果如下

3、不同环境下是否启动文档

我们有时方便完成一个项目，分多个配置文件，有dev，test，prod等，分别代表开发，测试，生产环境。在生产环境我们并不希望开启文档。

1、先有三个配置文件，在主配置文件启用dev配置文件

2、在配置类中添加

// 可运行文档的环境Profiles profiles = Profiles.of("dev", "test");// 返回是否包含运行环境的判断值boolean b = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2)    .apiInfo(apiInfo())    // 配置是否启动swagger,默认为true    .enable(b)    ...

3、如果在主配置文件启动prod就不会启动文档，无法访问地址

4、常用注解

Api

作用类上，说明类的作用

@Api(tags = {
   "页面数据接口"})@RestControllerpublic class PageController

ApiParam

作用于方法中的参数，说明参数的作用

public String findTableData(@ApiParam(name = "查询条件") @RequestBody PageVO pageVO)

ApiResponse 和 ApiResponses

ApiResponse作用于方法上，说明响应的信息。ApiResponses可包含多个ApiResponse

@ApiResponses({
   @ApiResponse(code = 200, message = "ok", response = ResultVo.class)})@RequestMapping({
   "/page1"})public String findTableData(@RequestBody PageVO pageVO) {

ApiImplicitParam 和 ApiImplicitParams

ApiImplicitParam作用于方法上，表示单独说明请求参数。ApiImplicitParams表示一组请求的参数

@ApiImplicitParams(@ApiImplicitParam(name = "pageVo", value = "查询参数"))

ApiImplicitParam 和 ApiImplicitParams

ApiImplicitParam作用于方法上，表示单独说明请求参数。ApiImplicitParams表示一组请求的参数

@ApiImplicitParams(@ApiImplicitParam(name = "pageVo", value = "查询参数"))

转载地址：http://oeugf.baihongyu.com/