Springboot：使用swagger便于协同开发

一、swagger简介

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

二、springboot整合swagger

1、导入pom

      <!-- springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- springfox-swagger-ui -->
        <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();
    }

三、设置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注解完成