Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于openApi3），这篇文章将介绍如何在 java 中使用 OpenApi3（swagger3）以及与swagger2的对比。
1.基本介绍
1.1 Open API
OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。
1.2 Swagger
swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）。swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。
1.3 SpringFox
SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，都未支持 OpenAPI3 标准。
补充：2020.7.14 发布了 3.0 支持 OpenAPI3，github 发布记录 但官网对 3.0 版本相关文档未完善，还是只有 swagger 2.0 相关的。
升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3）官方文档
1.4 swagger3 相关特性
- 支持 Spring 5，Webflux（仅请求映射支持，尚不支持功能端点）、Spring Integration
- 官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
- 与swagger2.0更好的规范兼容性
- 支持OpenApi 3.0.3
- 轻依赖 spring-plugin，swagger-core
1.5 SpringDoc
SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。
该组织下的项目支持swagger页面Oauth2登录（Open API3的内容），相较 SpringFox来说，它的支撑时间更长，无疑是更好的选择。但由于国内发展较慢，在国内不容易看到太多有用的文档，不过可以访问它的官网。它的使用了 swagger3（OpenAPI3），但 swagger3 并未对 swagger2 的注解做兼容，不易迁移，也因此，名气并不如 spring fox。
2.开始使用
2.1 从 spring-fox 迁移到 springdoc
依赖变更
pom.xml 里去掉 springfox 或者 swagger 的依赖，添加springdoc-openapi-ui。
- <dependency>
- <groupId>org.springdoc</groupId>
- <artifactId>springdoc-openapi-ui</artifactId>
- <version>1.5.2</version>
- </dependency>
2.2 Swagger3与 Swagger2注解对比使用
使用 swagger3 注解代替 swagger2 的（为可选项）
| Swagger3 | Swagger2 | 注解说明 |
| @Tag(name = “接口类描述”) | @Api | Controller 类 |
| @Operation(summary =“接口方法描述”) | @ApiOperation | Controller 方法 |
| @Parameters | @ApiImplicitParams | Controller 方法 |
| @Parameter(description=“参数描述”) |
@ApiImplicitParam @ApiParam |
Controller 方法上 @Parameters 里 Controller 方法的参数 |
|
@Parameter(hidden = true) @Operation(hidden = true) @Hidden |
@ApiIgnore | 排除或隐藏api |
| @Schema |
@ApiModel @ApiModelProperty |
DTO实体 DTO实体属性 |
Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。
@ApiParam和@ApiImplicitParam的功能是相同的，但是@ApiImplicitParam的适用范围更广。在非JAX-RS的场合（比如使用servlet提供HTTP接口），只能使用@ApiImplicitParam进行参数说明。我认为，这是因为接口并不显式展示入参的名称，所以没有地方去使用@ApiParam，只能在接口的方法声明下方写@ApiImplicitParam
2.3 Api 分组配置
Swagger2 配置：
@Bean
public Docket publicApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
.paths(PathSelectors.regex("/api/v1/public.*"))
.build()
.groupName("spring-app-public")
.apiInfo(apiInfo());
}
Swagger3配置：
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.setGroup("spring-app-public")
.pathsToMatch("/api/v1/public/**")
.build();
}
Swagger3用配置文件替代代码配置：
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/api/v1/public/**
swagger2 使用：
<!-- knife4j 接口文档工具 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-springdoc-ui</artifactId>
<version>3.0.3</version>
</dependency>
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
//.title("swagger-bootstrap-ui-demo RESTful APIs")
.description("# swagger-bootstrap-ui-demo RESTful APIs")
.termsOfServiceUrl("http://www.xx.com/")
.contact("[email protected]")
.version("1.0")
.build())
//分组名称
.groupName("2.X版本")
.select()
//这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
}
https://doc.xiaominfo.com/docs/action/springboot
knife4j的增强配置
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 自4.0版本，配置属性元数据全部改由spring-boot-configuration-processor自动生成，因此之前版本的驼峰命名全部修改成了横杠(-)代替
knife4j:
enable: true
documents:
-
group: 2.X版本
name: 接口签名
locations: classpath:sign/*
setting:
language: zh-CN
enable-swagger-models: true
enable-document-manage: true
swagger-model-name: 实体类列表
enable-version: false
enable-reload-cache-parameter: false
enable-after-script: true
enable-filter-multipart-api-method-type: POST
enable-filter-multipart-apis: false
enable-request-cache: true
enable-host: false
enable-host-text: 192.168.0.193:8000
enable-home-custom: true
home-custom-path: classpath:markdown/home.md
enable-search: false
enable-footer: false
enable-footer-custom: true
footer-custom-content: Apache License 2.0 | Copyright 2019-[浙江八一菜刀股份有限公司](https://gitee.com/xiaoym/knife4j)
enable-dynamic-parameter: false
enable-debug: true
enable-open-api: false
enable-group: true
cors: false
production: false
basic:
enable: false
username: test
password: 12313
在以前的版本中,开发者需要在配置文件中手动使用@EnableKnife4j来使用增强，自2.0.6版本后,只需要在配置文件中配置knife4j.enable=true即可不在使用注解
注意：要使用Knife4j提供的增强，knife4j.enable=true必须开启
https://doc.xiaominfo.com/docs/features/enhance
示例：
# https://doc.xiaominfo.com/knife4j
knife4j:
# 开启增强配置
enable: true
# 是否开启生产环境屏蔽 true:关闭swagger，false:开启swagger
production: false
basic:
# 是否开启认证
enable: false
# Basic认证用户名
username: admin
# Basic认证密码
password: 123456
标签：knife4j,enable,false,spring,swagger,true From： https://www.cnblogs.com/youxin/p/17990945