Springboot：使用swagger便于协同开发

川长思鸟来 2023-01-01 09:51 124阅读 0赞

### Springboot：使用swagger便于协同开发 ###

*  一、swagger简介
 *  二、springboot整合swagger
 *   *  1、导入pom
     *  2、编写配置类，将Docket注入容器中
 *  三、设置sawgger的运行环境、多人协作
 *  四、生成接口文档、接口测试

# 一、swagger简介 #

这里我在网上查了发现的大部分介绍`swagger`都是长篇大论，太过官方，这里简单概括：**`swagger`是一款能够快速生成接口文档，接口注释的优秀工具**

# 二、springboot整合swagger #

## 1、导入pom ##

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

## 2、编写配置类，将Docket注入容器中 ##

这里自己可以重写一个ApiInfo，更改属于自己的swagger简介

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
        //作者信息
        public static final Contact DEFAULT_CONTACT = new Contact("kexing", "https://kexing.site/", "1600342330@qq.com");
    
        //swagger信息
        private ApiInfo apiInfo(){ 
            return new ApiInfo(
                    "kexing's swagger 文档",
                    "不试试怎么知道",
                    "v1.0",
                    "https://kexing.site/",
                    DEFAULT_CONTACT,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList<VendorExtension>());
        }
    
        //配置swagger的Docket实例
        @Bean
        public Docket docket(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("可星")
                    .select()
                    //RequestHandlerSelectors 配置要扫描接口的方式
                    //basePackage：执行扫描的包
                    //any()：扫描全部
                    //none()：不扫描
                    //withClassAnnotation()：扫描类上的注解
                    //withMethodAnnotation()：扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("site.kexing"))
                    .build();
        }

![swagger][]

# 三、设置sawgger的运行环境、多人协作 #

@Bean
        public Docket docket(Environment environment){ 
            /** * 希望swagger在自己设置的环境中运行 */
            //设置swagger的环境
            Profiles profiles = Profiles.of("dev","test");
            //判断当前环境是否在swagger设置的环境中
            boolean flag = environment.acceptsProfiles(profiles);
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("可星")
                    .enable(flag)
                    .select()
                    //RequestHandlerSelectors 配置要扫描接口的方式
                    //basePackage：执行扫描的包
                    //any()：扫描全部
                    //none()：不扫描
                    //withClassAnnotation()：扫描类上的注解
                    //withMethodAnnotation()：扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("site.kexing"))
                    .build();
        }

通过`profiles`可以设置`swagger`能运行的环境，一般是开发和测试，当项目上线就不允许访问了，然后通过`environment.acceptsProfiles`可以判断`swagger`的环境与此时的项目环境是否一致，返回一个`boolean`，最后通过`enable(flag)`即可控制`swagger`的开启

**注入多个bean，通过groupName设置组名，然后设置一些上面的相关配置即可完成多人协作**

//多人协同开发 注入多个docket
        @Bean
        public Docket guofubing_docket(){ 
            return new Docket(DocumentationType.SWAGGER_2).groupName("guofubing");
        }

# 四、生成接口文档、接口测试 #

`User`：

@Data
    @AllArgsConstructor
    @NoArgsConstructor
    @ApiModel(value = "用户实体类")
    public class User { 
        @ApiModelProperty(value = "用户名")
        private String username;
        @ApiModelProperty(value = "密码")
        private String password;
    }

`@ApiModel`设置实体类的注释信息，`@ApiModelProperty`设置属性的注释信息

`UserController` ：

@Controller
    @Api(tags = "用户控制器")
    public class UserController { 
        //只要接口返回了实体类 swagger就会有显示
        @ResponseBody
        @PostMapping(value = "/user")
        public User getUser(){ 
            return new User("kexing","123");
        }
    
        @ResponseBody
        @GetMapping(value = "/getuname")
        public String getUsername(String username){ 
            return username;
        }
    
        @PostMapping(value = "/topage")
        @ApiOperation(value = "返回测试视图")
        public String toPage(){ 
            return "test";
        }
    }

控制器也可以设置注释信息，通过`@Api`，`@ApiOperation`注解完成  
![swagger][swagger 1]

![swagger][swagger 2]

[swagger]: /images/20221120/e2fbb5cfdcea4dc6a4c02becd261c5b9.png
[swagger 1]: https://img-blog.csdnimg.cn/20210101223459631.jpg?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNDQyMzM1,size_16,color_FFFFFF,t_70
[swagger 2]: https://img-blog.csdnimg.cn/20210101223750370.jpg?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzQzNDQyMzM1,size_16,color_FFFFFF,t_70