springboot整合Swagger

Tips：Swagger2和Swagger3的整合方式稍有区别，请按需选择。

springboot整合Swagger2

1、pom.xml添加maven依赖（以2.9.2为例）

<!-- swagger2相关依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

2、增加配置类Swagger2Config.java

注意使用：DocumentationType.SWAGGER_2

package com.my.lvyyd.config;

import org.springframework.context.annotation.Bean;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableSwagger2  // 允许使用swagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi(Environment environment) {
        // 配置 default/dev/test 环境可用，其他环境不可用
        Profiles profile = Profiles.of("default", "dev", "test");
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)                             // 是否启用
                .groupName("lvyyd")                       // 组别，区分接口提供者，默认default
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.my.lvyyd.controller"))   // 根据包名扫描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My Swagger2")                      // 设置文档的标题
                .description("My API 接口文档")             // 设置文档的描述
                .version("V1.0")                           // 设置文档的版本信息
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                .build();
    }

}

4、Api接口编写

package com.my.lvyyd.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "swagger2测试类")
@RestController
public class Swagger2TestContoller {

    @ApiOperation("swagger2测试方法")
    @GetMapping("/hello")
    public String Hello() {
        return "hello";
    }

}

常见注解描述：
@Api：修饰整个类，描述Controller的作用，与tags搭配使用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

4、启动springboot应用，访问swagger页面

http://localhost:8080/swagger-ui.html

springboot整合Swagger3

1、pom.xml添加maven依赖（以3.0.0为例）

<!-- swagger3相关依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2、启动类上添加注解 @EnableOpenApi

3、增加配置类Swagger3Config.java

注意使用：DocumentationType.OAS_30

package com.my.lvyyd.config;

import org.springframework.context.annotation.Bean;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger3Config {

    @Bean
    public Docket createRestApi(Environment environment) {
        // 配置 default/dev/test 环境可用，其他环境不可用
        Profiles profile = Profiles.of("default", "dev", "test");
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(flag)                             // 是否启用
                .groupName("lvyyd")                       // 组别，区分接口提供者，默认default
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.my.lvyyd.controller"))   // 根据包名扫描
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My Swagger3")                      // 设置文档的标题
                .description("My API 接口文档")             // 设置文档的描述
                .version("V1.0")                           // 设置文档的版本信息
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                .build();
    }

}

4、Api接口编写

package com.my.lvyyd.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class Swagger3TestContoller {

    @ApiOperation("swagger3测试方法")
    @GetMapping("/hello")
    public String Hello() {
        return "hello";
    }

}

常见注解描述：
@Api：修饰整个类，描述Controller的作用，与tags搭配使用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

5、启动springboot应用，访问swagger页面

http://localhost:8080/swagger-ui/index.html