SpringBoot 整合 Swagger

本文以Spring Boot 项目为例，集成Swagger文档工具。

IDEA 创建 Spring Boot项目请转到：

IDEA SpringBoot Mybatis Mysql 入门小案例_LZW15082682930的博客-CSDN博客

一、引入Swagger依赖

    io.springfox
    springfox-boot-starter
    3.0.0

 二、编写配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;


/**
 * @Author LZW
 * @Description
 * @Date 2022-03-29 21:23
 * @Version 1.0
 */
@Configuration
public class SwaggerConfig {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo());
    }


    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger 接口文档")
                .description("Api说明")
                .contact(new Contact("LZW", "null", "null"))
                .version("1.0")
                .build();
    }
}

 或者

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;

/**
 * Swagger 配置类
 */
@Configuration
public class SwaggerConfig {
    /**
     * 配置swagger的Docket bean
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
                .apiInfo(createApiInfo());
    }

    /**
     * 配置swagger的ApiInfo bean
     *
     * @return
     */
    @Bean
    public ApiInfo createApiInfo() {
        return new ApiInfo("Api文档"
                , "Api文档"
                , "3.0"
                , ""
                , new Contact("LZW", "",
                "")
                , "Apache 2.0"
                , "http://www.apache.org/licenses/LICENSE-2.0"
                , new ArrayList());
    }
}

 附ApiInfo源码，根据需要进行配置即可

    public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact, String license, String licenseUrl, Collection vendorExtensions) {
        this.title = title;
        this.description = description;
        this.version = version;
        this.termsOfServiceUrl = termsOfServiceUrl;
        this.contact = contact;
        this.license = license;
        this.licenseUrl = licenseUrl;
        this.vendorExtensions = new ArrayList(vendorExtensions);
    }

三、启动项目，访问文档

浏览器访问地址：

默认地址：

http://IP地址+端口号+swagger-ui/

http://localhost:8086/swagger-ui/

 

 四、常用配置说明

@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· div（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：用在属性上，描述响应类的属性

五、关闭swagger

application.yml配置

# 生产环境设置 false
springfox:
  documentation:
    swagger-ui:
      enabled: true

配置类

/**
* 配置swagger的Docket bean
* @return
*/
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30) // 指定swagger3.0版本
                .enable(false) // 开关
                .apiInfo(createApiInfo());
}

完整项目地址： 

GitHub - Li-zw/swagger-repositories: swagger 学习仓库