Swagger3 在线文档(新一代) - 《术@速[IT]》

Swagger应该是大部分Java程序员都有听说过或者使用过，这里推荐使用
Knife4j是一个为Swagger接口文档赋能的工具，提供了我认为更加良好的操作体验，版本已经升级到Knife4j 3.0.2了。
第一步引用[Maven] ：3.0.2
SpringBoot
<dependency> `` <groupId>``com.spring4all``</groupId> `` <artifactId>``swagger-spring-boot-starter``</artifactId> `` <version>``${swagger2-springboot}``</version> ``</dependency> ``<dependency> `` <groupId>``io.springfox``</groupId> `` <artifactId>``springfox-boot-starter``</artifactId> `` <version>``${springfox.version}``</version> ``</dependency> ``<dependency> `` <groupId>``com.github.xiaoymin``</groupId> `` <artifactId>``knife4j-spring-boot-starter``</artifactId> `` <version>``${knife4j.version}``</version> ``</dependency>

SpringCloud

在Spring Cloud的微服务架构下,每个微服务其实并不需要引入前端的Ui资源,因此在每个微服务的Spring Boot项目下,引入knife4j提供的微服务starter
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-micro-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
在网关聚合文档服务下,可以再把前端的ui资源引入
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
第二步代码部分(可以直接引用):
package com.honggv.cloud.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))
.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”, “”, “798604766@qq.com”))
.version(“1.0”)
.description(“API文档”)
.build();
}
/*
__ 生成全局通用参数 * @return
** */__ _private List getGlobalRequestParameters() {
List parameters = new ArrayList<>();
parameters.add(new RequestParameterBuilder()
.name(“Authorization”)
.description(“令牌”)
.required(false)
.in(ParameterType._HEADER)
.build());
parameters.add(new RequestParameterBuilder()
.name(“clientType”)
.description(“平台标识”)
.required(false)
.in(ParameterType.HEADER)
.build());
return parameters;
}
_/
* 生成通用响应信息 */
__ _private List getGlobalResponseMessage() {
List responseList = new ArrayList<>();
responseList.add(new ResponseBuilder().code(“404”).description(“找不到资源”).build());
return responseList;
}
}

第三步配置：
Knife4j自2.0.6版本开始,将目前在Ui界面中一些个性化配置剥离,开发者可以在后端进行配置，并且提供的knife4j-spring-boot-strater组件自动装载
spring.factories配置如下：

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration

在Spring Boot配置文件中,完整的配置如下:

knife4j:
  enable: true
  documents:
    -
      group: 2.X版本
      name: 接口签名
      locations: classpath:sign/*
  setting:
    language: zh-CN
    enableSwaggerModels: true
    enableDocumentManage: true
    swaggerModelName: 实体类列表
    enableVersion: false
    enableReloadCacheParameter: false
    enableAfterScript: true
    enableFilterMultipartApiMethodType: POST
    enableFilterMultipartApis: false
    enableRequestCache: true
    enableHost: false
    enableHostText: 192.168.0.193:8000
    enableHomeCustom: true
    homeCustomLocation: classpath:markdown/home.md
    enableSearch: false
    enableFooter: false
    enableFooterCustom: true
    footerCustomContent: Apache License 2.0 | Copyright  2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
    enableDynamicParameter: false
    enableDebug: true
    enableOpenApi: false
    enableGroup: true
  cors: false
  production: false
  basic:
    enable: false
    username: test
    password: 12313

在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解
注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfiguration {
    /*引入Knife4j提供的扩展类*/
   private final OpenApiExtensionResolver openApiExtensionResolver;
    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
@Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="2.X版本";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                .paths(PathSelectors.any())
                .build()
                //赋予插件体系
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfiguration {
    /*引入Knife4j提供的扩展类*/
   private final OpenApiExtensionResolver openApiExtensionResolver;
    @Autowired
    public SwaggerConfiguration(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }
@Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        String groupName="2.X版本";
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .host("https://www.baidu.com")
                .apiInfo(apiInfo())
                .groupName(groupName)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.bootstrap.ui.demo.new2"))
                .paths(PathSelectors.any())
                .build()
                //赋予插件体系
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
        return docket;
    }

官方文档: https://doc.xiaominfo.com/knife4j/documentation

访问：http://ip:port/doc.html

简单而实用…..