Springboot 2.3.4 整合swagger3 支持导出离线文档 再也不需要以后手动编写接口文档了

欢迎大家进群，一起探讨学习

微信公众号，每天给大家提供技术干货

博主技术笔记

博主网站地址1

博主网站地址2

博主开源微服架构前后端分离技术博客项目源码地址，欢迎各位star

一：Springboot 2.3.4 整合swagger3 支持导出离线文档 再也不需要以后手动编写接口文档了

一、引用mavem依赖

	<!--引入swagger3 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

二、swagger 配置

代码如下（示例）：

package com.yoostar.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.List;

/**
 * swagger 配置
 *
 * @author bright
 */
@Configuration
@EnableOpenApi
public class Swagger3Config {

    /**
     * swagger3的配置文件
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage())
                .globalResponses(HttpMethod.DELETE, getGlobalResponseMessage())
                .globalResponses(HttpMethod.PUT, getGlobalResponseMessage());
    }

    /**
     * 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
     */
    private ApiInfo apiInfo() {
        // 获取工程名称
        String projectName = System.getProperty("user.dir");
        return new ApiInfoBuilder()
                .title(projectName.substring(projectName.lastIndexOf("\\") + 1) + " API接口文档")
                .contact(new Contact("bright", "", "[email protected]"))
                .version("1.0")
                .description("API文档")
                .build();
    }

    /**
     * 生成全局通用参数
     *
     * @return
     */

    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("x-access-token")
                .description("令牌")
                .required(false)
                .in(ParameterType.HEADER)
                .build());
        parameters.add(new RequestParameterBuilder()
                .name("Equipment-Type")
                .description("产品类型")
                .required(false)
                .in(ParameterType.HEADER)
                .build());
        return parameters;
    }

    /**
     * 生成通用响应信息
     *
     * @return
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
        return responseList;
    }
}

3.启动程序

4.访问

http://127.0.0.1:8085/swagger-ui/index.html

5.注意事项

1,生产环境中，要关闭swagger

application.properties中配置:

  springfox.documentation.swagger-ui.enabled=false
  
  knife4j.enable: true #停用Swagger文档

二：集成增强文档knife4j

1.在pom.xml中增加knife4j的相关依赖；

 		<!--Knife4j-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

在Swagger2Config中增加一个@EnableKnife4j注解，该注解可以开启knife4j的增强功能

运行我们的SpringBoot应用，访问API文档地址即可查看：http://localhost:8088/doc.html

首先在Authorize功能中添加登录返回的Token；

之后在每个接口中就可以看到已经在请求头中携带了Token信息。

离线文档
knife4j支持导出离线文档，方便发送给别人，支持Markdown格式。

直接选择文档管理->离线文档功能，然后选择下载Markdown即可；

我们来查看下导出的Markdown离线文档，还是很详细的。

全局参数
knife4j支持临时设置全局参数，支持两种类型query(表单)、header(请求头)。

比如我们想要在所有请求头中加入一个参数appType来区分是android还是ios调用，可以在全局参数中添加；

此时再调用接口时，就会包含appType这个请求头了。

忽略参数属性
有时候我们创建和修改的接口会使用同一个对象作为请求参数，但是我们创建的时候并不需要id，而修改的时候会需要id，此时我们可以忽略id这个属性。

比如这里的创建商品接口，id、商品数量、商品评论数量都可以让后台接口生成无需传递，可以使用knife4j提供的@ApiOperationSupport注解来忽略这些属性；

各位大佬关注下