springboot集成swagger

在前后端的开发协助中往往会遇到数据统一的问题，假如说前后端操作的json数据从最开始不统一，或者说中途json数据格式变更了，如果项目没有及时作出对应的调整，那就会牵扯出一系列麻烦的问题。因此就需要有一个东西能够实时的、清晰的监控并展示后台接口数据的格式，从而在数据内容变更的最短时间内了解并化解麻烦，这就是swagger的作用。

一：新建springboot项目

导入依赖：

<!-- 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>

建立对应config文件夹，以及SwaggerConfig文件，配置swagger:

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

启动项目，访问 http://localhost:8044/swagger-ui.html
因为我这里已经随便建立了一个Controller并写了一个helloword接口，所以可以出现内容。

该页面在swagger-jar下

二：swagger配置自定义扫描接口

SwaggerConfig:

package com.swagger.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
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //接口扫描方式
                 /**
                 * basePackage指定扫描的包
                 *withClassAnnoation 扫描类上的注解
                 *withMethodAnnoation 扫描方法上的注解
                 */
                 .apis(RequestHandlerSelectors.basePackage("com.swagger.Controller"))
                .build();
    }


    private ApiInfo apiInfo(){
        Contact contact = new Contact("deeeelete","http://localhost","[email protected]");

        return  new ApiInfo("Deeeelete", "Api Documentation", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

这样就指定扫描Controller下的接口了。

以及根据配置环境选择性开启swagger和一些分组配置之类的。

package com.swagger.Config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
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
@EnableSwagger2
public class SwaggerConfig {


    @Bean
    public Docket docket(Environment environment){
        //当前环境
        Profiles profiles = Profiles.of("dev");
        //获取项目环境可进行判断
        boolean flag = environment.acceptsProfiles(profiles);
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("docket")
                .enable(flag) //如果不是dev环境关闭swagger
                .select()
                //接口扫描方式
                /**
                 * basePackage指定扫描的包
                 *withClassAnnoation 扫描类上的注解
                 *withMethodAnnoation 扫描方法上的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.swagger.Controller"))
                //过滤路径
                //.paths(PathSelectors.ant("swagger/**"))
                .build();
    }

    @Bean
    public Docket docket1(Environment environment){
        //当前环境
        Profiles profiles = Profiles.of("dev");
        //获取项目环境可进行判断
        boolean flag = environment.acceptsProfiles(profiles);
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("docket1")
                .enable(flag) //如果不是dev环境关闭swagger
                .select()
                .apis(RequestHandlerSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("deeeelete","http://localhost","[email protected]");

        return  new ApiInfo("Deeeelete", "Api Documentation", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

三：swagger注释

@ApiModel：给类加注释
@ApiModelProperty：给变量加注释
@ApiOperation: 给接口层方法加注释
@ApiParam：给接口方法参数加注释

通过在实体类中加注释，可以在swagger ui中更详细的展示：

package com.swagger.Pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户id")
    private int id;

    @ApiModelProperty("用户名")
    private String name;

    @ApiModelProperty("用户密码")
    private String password;

    public User() {
        super();
    }

    public User(int id, String name, String password) {
        this.id = id;
        this.name = name;
        this.password = password;
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

接口层：

   @PostMapping
    @ApiOperation("controller 注释")
    public User getUser(@ApiParam("用户名") String name){
        name="deeeelete";
        User user = new User();
        user.setName(name);
        return user;
    }

接口也可以在线测试：

资料参考：

https://www.bilibili.com/video/BV1PE411i7CV
https://swagger.io/