Swagger2快速上手

短命女 2021-09-23 22:38 410阅读 0赞

# 1、背景 #

**相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。**

# 2、Swagger是什么？它能干什么？ #

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMjI5NTQz_size_16_color_FFFFFF_t_70]  
发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。

但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

# 3、SpringBoot整合Swagger #

**1、Maven依赖**

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>

**2、SwaggerConfig配置类**

package com.lcy.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    
    @Configuration
    //开启swagger2
    @EnableSwagger2
    public class SwaggerConfig { 
    
    
    // .groupName() 多人协作开发时需要配置多个分组
    
        @Bean
        public Docket docketZS() { 
            return new Docket(DocumentationType.SWAGGER_2).groupName("zhangsan");
        }
    
        @Bean
        public Docket docketLS() { 
            return new Docket(DocumentationType.SWAGGER_2).groupName("lisi");
        }
    
        @Bean
        public Docket docketWW() { 
            return new Docket(DocumentationType.SWAGGER_2).groupName("wangwu");
        }
    
    
        //配置了Swagger的Docket的bean实例
        // enable(true) 是否开启swagger 默认为true
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("lichenyang")
                    .apiInfo(apiINfo())
                    .enable(true)
                    .select()
                    //配置要扫描接口的方式
                    /** * RequestHandlerSelectors 配置要扫描接口的方式 * .basePackage() ：指定要扫描的包 * .any():扫描全部 * .none()：不扫描 * .withClassAnnotation()：扫描类上的注解 * .withMethodAnnotation();扫描方法上的注解 */
                    .apis(RequestHandlerSelectors.basePackage("com.lcy.controller"))
    // .paths() 过滤什么路径
    // .paths(PathSelectors.ant("/com/**"))
                    .build();
        }
    
        // 配置Swagger信息=apiInfo
        private ApiInfo apiINfo() { 
    // 作者信息
            Contact contact = new Contact("lcy", "https://lichenyang.blog.csdn.net/", "1105636101@qq.com");
            return new ApiInfo(
                    "lcy的Swagger文档",
                    "生活不止眼前的苟且",
                    "version_1.0",
                    "https://lichenyang.blog.csdn.net/",
                    contact,
                    "Apacher 2.0",
                    "https://lichenyang.blog.csdn.net/",
                    new ArrayList<>()
            );
        }
    }

**3、controller类示例**

package com.lcy.controller;
    
    import com.lcy.pojo.User;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    
    @RestController
    public class HelloController { 
    
        @RequestMapping(value = "Hello", method = RequestMethod.POST)
        @ApiOperation("Hello 接口文档")
        public String helloname(@ApiParam(value = "用户名") @RequestParam String name) { 
            return "Hello World！！！" + name;
        }
    }

**4、swagger页面**  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMjI5NTQz_size_16_color_FFFFFF_t_70 1]

# 4、Swagger常用注解 #

**@Api 注解可以用来标记 Controller 的功能**

**@ApiOperation 注解用来标记一个方法的作用**

**@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入**

**@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中**

**@ApiModel 如果参数是一个对象，则需要在对象所在的类上加上此注解**

**@ApiModelProperty 如果参数是一个对象，则需要在对应的属性上加上此注解，还需要在对象所在的类上加上 @ApiModel**

**@ApiIgnore 注解标识此参数可以忽略**

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMjI5NTQz_size_16_color_FFFFFF_t_70]: /images/20210923/5b547e49b50344fd97d27dd5c58fd145.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzMjI5NTQz_size_16_color_FFFFFF_t_70 1]: /images/20210923/800305aacce14670896fa7736e1155f6.png