swagger 3 的使用

Open API

Swagger

SpringFox

补充：2020.7.14 发布了 3.0 支持 OpenAPI3， github 发布记录 但官网对 3.0 版本相关文档未完善，还是只有 swagger 2.0 相关的。
升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3）官方文档

3.0 相关特性

• 支持 Spring 5 ， Webflux （仅请求映射支持，尚不支持功能端点）、 Spring Integration
• 补充官方在 spring boot 的自动装配 pringfox-boot-starter 以后可以直接依赖一个 dependency
• 与2.0更好的规范兼容性
• 支持OpenApi 3.0.3
• 轻依赖 spring-plugin ， swagger-core
• 现有的swagger2批注将继续有效并丰富开放式API 3.0规范

SpringDoc

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

该组织下的项目支持swagger页面Oauth2登录（Open API3的内容），相较 SpringFox来说，它的支撑时间更长，无疑是更好的选择。但由于国内发展较慢，在国内不容易看到太多有用的文档，不过可以访问它的 官网 。它的使用了 swagger3（OpenAPI3），但 swagger3 并未对 swagger2 的注解做兼容，不易迁移，也因此，名气并不如 spring fox。

从 spring-fox 迁移到 springdoc

pom.xml 里去掉 springfox 或者 swagger 的依赖。添加 springdoc-openapi-ui 。

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.3.1</version>
   </dependency>
使用 swagger3 注解代替 swagger2 的（可选）
 
这一步是可选的，因为改动太大，故 springfox对旧版的 swagger做了兼容处理。
 但不知道未来会不会不兼容，这里列出如何用 swagger 3 的注解（已经在上面引入）代替 swagger 2 的
 (注意修改 swagger 3 注解的包路径为io.swagger.v3.oas.annotations.)
 
对应关系为：
 
swagger2
OpenAPI 3
注解位置
@Api
@Tag(name = “接口类描述”)
Controller 类上
@ApiOperation
@Operation(summary =“接口方法描述”)
Controller 方法上
@ApiImplicitParams
@Parameters
Controller 方法上
@ApiImplicitParam
@Parameter(description=“参数描述”)
Controller 方法上 @Parameters 里
@ApiParam
@Parameter(description=“参数描述”)
Controller 方法的参数上
@ApiIgnore
@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden
-
@ApiModel
@Schema
DTO类上
@ApiModelProperty
@Schema
DTO属性上
 
Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。
 
修改Api 分组（当且仅当你之前定义了多个 Docket Bean）
 
   @Bean
    public Docket publicApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                .paths(PathSelectors.regex("/public.*"))
                .build()
                .groupName("springshop-public")
                .apiInfo(apiInfo());
    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
                .paths(PathSelectors.regex("/admin.*"))
                .build()
                .groupName("springshop-admin")
                .apiInfo(apiInfo());
   @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-public")
                .pathsToMatch("/public/**")
                .build();
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .setGroup("springshop-admin")
                .pathsToMatch("/admin/**")
                .build();
如果之前只有一个 Docket，则把他删了，用配置文件替代它
 
springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
swagger ui在代理的后面，如 nginx
 
参见这篇
 https://springdoc.org/faq.html#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.
 
自定义 Swagger UI
 
https://springdoc.org/faq.html#how-can-i-configure-swagger-ui.
 
在文档中隐藏某个接口或者 Controller
 
https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation-.
				
Swagger 3 的使用
Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于openApi3），这篇文章将介绍如何在 java 中使用 OpenApi3（swagger3）以及与swagger2的对比。
1.基本介绍
1.1 Open API
OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。
1.2 Swagger
swagger 是一个 api 文档维护组织，后来成为了 Open AP
				
Sprinboot2.4整合Swagger3（springdoc-openapi-ui）一、创建Springboot项目，引入pom依赖二、配置类请求头携带token三、配置文件四、接口定义五、实现类六、实体类定义七、运行项目查看效果
参考文档：https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X—Annotations
一、创建Springboot项目，引入pom依赖
        <dependency>
				
文章目录前言一、swagger 3 的使用SwaggerSpringFox3.0 相关特性SpringDoc二、从 spring-fox 迁移到 springdoc三、使用 swagger3 注解代替 swagger2 的（可选）
Swagger2（基于openApi3）已经在17年停止维护了，取而代之的是 sagger3（基于openApi3），而国内几乎没有 sagger3使用的文档，百度搜出来的都是swagger2的使用，这篇文章将介绍如何在 java 中使用 openApi3（swagge
tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value=“说明方法的用途、作用”
notes=“方法的备注说明”
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImpli...
1.这里使用的版本：springfox-swagger2（2.4）springfox-swagger-ui （2.4）
2.这里是说明常用注解的含义和基本用法（也就是说已经对swagger进行集成完成）
没有集成的请参见SpringBoot集成springfox-swagger2构建restful APISpringMVC集成springfox-swagger2构建restful API官...
				
SpringBoot集成Swagger3–在线API文档（详细步骤+图解）
Open API
OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。
Swagger
swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。
国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）
swagger2的包