Spring Doc OpenAPI3.0 抛弃SpringFox拥抱SpringDoc

这篇具有很好参考价值的文章主要介绍了Spring Doc OpenAPI3.0 抛弃SpringFox拥抱SpringDoc。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

Spring Doc

1 简介

SpringDoc是SpringBoot 的API文档工具。官网:https://springdoc.org/

在使用SpringBoot 2.6以前去创建API文档工具一般会采用SpringFox提供的Swagger库,但是由于SpringBoot版本的不断升级和SpringFox摆烂不更新,导致了SpringBoot2.6之后的项目无法使用SpringFox去生成API文档,或者可以使用但是有很多的bug。

SpringDoc是一款可以结合SpringBoot使用API文档生成工具,基于OpenAPI 3,而且项目维护和社区都在不断更新,不仅支持SpringMVC,而且还支持Spring WebFlux项目。

下图为SpringDoc的架构图的总体概述。
springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

2 基本使用

2.1 新建项目并导入maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

2.2 使用注解标记接口

2.2.1 常用注解
注解 描述
@Tag 标记在接口类上,用来设置 Controller 的名称和描述
@Parameter/@Parameters 用来设置请求参数的描述
@Operation 对接口方法的描述,可以设置接口的名称
@ApiResponse/@ApiResponses 用来配置响应
@Schema 标记在模型(model)类上或类的属性上,进行标注解释。
2.2.2 测试Controler Demo

TestController

package org.example.controller.test;
/**
 * 省略import
 */
@Tag(name = "测试接口", description = "定义测试接口")
@RestController
@RequestMapping("/test")
public class TestController {
    @Operation(summary = "get测试接口", description = "返回id")
    @Parameter(name = "id", description = "参数ID", example = "123456")
    @ApiResponse(responseCode = "403", description = "无权限")
    @GetMapping("/get")
    public Map<String, Object> get(@Parameter(description = "id") String id) {
        Map<String, Object> res = new HashMap<>(1);
        res.put("id", id);
        return res;
    }
}

UserController

package org.example.controller.user;
/**
 * 省略import
 */
@Tag(name = "用户接口", description = "定义用户接口")
@RestController
@RequestMapping("/user")
public class UserController {
    @Operation(summary = "post测试接口", description = "返回username")
    @Parameter(name = "username", description = "参数username", example = "username")
    @ApiResponse(responseCode = "403", description = "无权限")
    @PostMapping("/post")
    public Map<String, Object> get(@Parameter(description = "用户名") String username) {
        Map<String, Object> res = new HashMap<>(1);
        res.put("username", username);
        return res;
    }
}

2.3 编写SpringDocConfig

2.3.1 常用springdoc的配置
package org.example.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @author zhong
 */
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI defaultOpenAPI() {
//        return new OpenAPI()
//                .info(info())
//                .externalDocs(documentation())
//                .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
//                        .description("JWT认证").scheme("bearer").bearerFormat("JWT")));


        return new OpenAPI().
                info(info())
                .externalDocs(documentation());
    }

    public Info info() {
        return new Info()
                .title("SpringDoc OpenApi")
                .version("V1.0.0")
                .description("测试spring doc open api")
                .license(new License().name("许可证名称").url("许可证地址"))
                .contact(new Contact().name("联系人").url("联想人链接"))
                .summary("概要");
    }

    public ExternalDocumentation documentation() {
        return new ExternalDocumentation().description("文档描述").url("文档地址");
    }

    @Bean
    public GroupedOpenApi testApi() {
        return GroupedOpenApi.builder()
                .displayName("测试接口")
                .group("test")
                .packagesToScan("org.example.controller.test")
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .displayName("用户接口")
                .group("user")
                .packagesToScan("org.example.controller.user")
                .addOpenApiCustomiser(openApiCustomiser())
                .addOperationCustomizer(operationCustomizer())
                .build();
    }

    public OpenApiCustomiser openApiCustomiser() {
        return api ->
                api.components(new Components()
                        .addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                                .description("JWT认证").scheme("bearer").bearerFormat("JWT"))
                );
    }

    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
            return operation;
        };
    }
}
2.3.2 关于接口鉴权问题(jwt方式)

如以上配置所示,user接口设置了鉴权设置

对一个分组的接口添加鉴权的方式

@Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .displayName("用户接口")
                .group("user")
                .packagesToScan("org.example.controller.user")
                .addOpenApiCustomiser(openApiCustomiser())
                .addOperationCustomizer(operationCustomizer())
                .build();
}
public OpenApiCustomiser openApiCustomiser() {
    return api ->
            api.components(new Components()
                    .addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                            .description("JWT认证").scheme("bearer").bearerFormat("JWT"))
            );
}

public OperationCustomizer operationCustomizer() {
    return (operation, handlerMethod) -> {
        operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
        return operation;
    };
}

如果嫌麻烦,可以设置全局设置

例如配置代码注释的部分添加全局配置

 @Bean
    public OpenAPI defaultOpenAPI() {
        return new OpenAPI()
                .info(info())
                .externalDocs(documentation())
                .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("认证").type(SecurityScheme.Type.HTTP)
                        .description("JWT认证").scheme("bearer").bearerFormat("JWT")));

    }

2.4 启动效果

访问http://localhost:8080/swagger-ui/index.html

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

2.5 一些application的配置说明

2.5.1 springdoc-openapi 核心属性

官方链接:https://springdoc.org/#springdoc-openapi-core-properties

参数名称 默认值 描述
springdoc.api-docs.path /v3/api-docs String, 用于 Json 格式的 OpenAPI 文档的自定义路径。
springdoc.api-docs.enabled true Boolean. 禁用 springdoc-openapi 端点(默认为 /v3/api-docs)。
springdoc.packages-to-scan * List of Strings.要扫描的包列表(逗号分隔)
springdoc.paths-to-match /* List of Strings.要匹配的路径列表(逗号分隔)
springdoc.produces-to-match /* List of Strings.The list of produces mediaTypes to match (逗号分隔)
springdoc.headers-to-match /* List of Strings.要匹配的标题列表(逗号分隔)
springdoc.consumes-to-match /* List of Strings.要匹配的消耗媒体类型列表(逗号分隔)
springdoc.paths-to-exclude List of Strings.要排除的路径列表(逗号分隔)
springdoc.packages-to-exclude List of Strings.要排除的包列表(逗号分隔)
springdoc.default-consumes-media-type application/json String. 默认使用媒体类型。
springdoc.default-produces-media-type **/** String.默认产生媒体类型。
springdoc.cache.disabled false Boolean. 禁用计算 OpenAPI 的 springdoc-openapi 缓存。
springdoc.show-actuator false Boolean. 显示执行器端点。
springdoc.auto-tag-class true Boolean. 禁用 springdoc-openapi 自动标签。
springdoc.model-and-view-allowed false Boolean. 允许带有 ModelAndView 返回的 RestControllers 出现在 OpenAPI 描述中。
springdoc.override-with-generic-response true Boolean. 当为 true 时,自动将 @ControllerAdvice 响应添加到所有生成的响应中。
springdoc.api-docs.groups.enabled true Boolean. 禁用 springdoc-openapi 组。
springdoc.group-configs[0].group String.群名
springdoc.group-configs[0].display-name String.组的显示名称。
springdoc.group-configs[0].packages-to-scan * List of Strings.要扫描组的包列表(逗号分隔)
springdoc.group-configs[0].paths-to-match /* List of Strings.组匹配的路径列表(逗号分隔)
springdoc.group-configs[0].paths-to-exclude `` List of Strings.要为组排除的路径列表(逗号分隔)
springdoc.group-configs[0].packages-to-exclude List of Strings.要排除的包列表(逗号分隔)
springdoc.group-configs[0].produces-to-match /* List of Strings.The list of produces mediaTypes to match (逗号分隔)
springdoc.group-configs[0].consumes-to-match /* List of Strings.要匹配的消耗媒体类型列表(逗号分隔)
springdoc.group-configs[0].headers-to-match /* List of Strings.要匹配的标题列表(逗号分隔)
springdoc.webjars.prefix /webjars String, 把swagger-ui的URL可见的webjars前缀换成spring-webflux。
springdoc.api-docs.resolve-schema-properties false Boolean. 在@Schema 上启用属性解析器(名称、标题和描述)。
springdoc.remove-broken-reference-definitions true Boolean. 禁用删除损坏的引用定义。
springdoc.writer-with-default-pretty-printer false Boolean. 启用 OpenApi 规范的漂亮打印。
springdoc.model-converters.deprecating-converter.enabled true Boolean. 禁用弃用模型转换器。
springdoc.model-converters.polymorphic-converter.enabled true Boolean. 禁用多态模型转换器。
springdoc.model-converters.pageable-converter.enabled true Boolean. 禁用可分页模型转换器。
springdoc.model-converters.sort-converter.enabled true Boolean. 禁用排序转换器。
springdoc.use-fqn false Boolean. 启用完全限定名称。
springdoc.show-endpoint false Boolean. 使 spring security 登录端点可见。
springdoc.pre-loading-enabled false Boolean. 预加载设置以在应用程序启动时加载 OpenAPI。
springdoc.writer-with-order-by-keys false Boolean. 启用确定性/字母顺序。
springdoc.use-management-port false Boolean. 在执行器管理端口上公开 swagger-ui。
springdoc.disable-i18n false Boolean. 使用 i18n 禁用自动翻译。
springdoc.show-spring-cloud-functions true Boolean. 显示 spring-cloud-function Web 端点。
springdoc.api-docs.version openapi_3_0 String. 选择OpenAPI 3.0OpenAPI 3.1(使用值OPENAPI_3_1)。
springdoc.default-flat-param-object false Boolean. 默认展平参数。
springdoc.default-support-form-data false Boolean. 指定api接受表单数据时默认设置参数为表单数据。
springdoc.nullable-request-parameter-enabled true Boolean. 在 Kotlin 中默认启用对可空请求参数的支持。
springdoc.show-oauth2-endpoints false Boolean. 使 spring security oauth2-endpoint 可见。
2.5.2 swagger-ui核心属性

官方链接https://springdoc.org/#swagger-ui-properties

参数名称 默认值 描述
springdoc.swagger-ui.path /swagger-ui.html String, 用于 swagger-ui HTML 文档的自定义路径。
springdoc.swagger-ui.enabled true Boolean. 禁用 swagger-ui 端点(默认为 /swagger-ui.html)。
springdoc.swagger-ui.configUrl /v3/api-docs/swagger-config String. 从中获取外部配置文档的 URL。

2 从SpringFox迁移

  • 删除 springfox 和 swagger 2 依赖项。添加springdoc-openapi-ui依赖项。
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>1.7.0</version>
   </dependency>
  • 用 swagger 3 注释替换 swagger 2 注释(它已经包含在springdoc-openapi-ui依赖项中)。swagger 3 注释的包是io.swagger.v3.oas.annotations.
    • @Api@Tag
    • @ApiIgnore@Parameter(hidden = true)@Operation(hidden = true)@Hidden
    • @ApiImplicitParam@Parameter
    • @ApiImplicitParams@Parameters
    • @ApiModel@Schema
    • @ApiModelProperty(hidden = true)@Schema(accessMode = READ_ONLY)
    • @ApiModelProperty@Schema
    • @ApiOperation(value = "foo", notes = "bar")@Operation(summary = "foo", description = "bar")
    • @ApiParam@Parameter
    • @ApiResponse(code = 404, message = "foo")@ApiResponse(responseCode = "404", description = "foo")
  • 如果您使用一个对象来捕获多个请求查询参数,请注释该方法参数@ParameterObject
  • 此步骤是可选的:仅当您有多个 Docketbeans 时才用GroupedOpenApibeans 替换它们。

前:

  @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.*"))
              .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
              .build()
              .groupName("springshop-admin")
              .apiInfo(apiInfo());
  }

现在:

  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }

如果你只有一个 Docket - 删除它并添加属性到你的application.properties

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
  • 添加OpenAPI类型的bean。参见示例:
  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }

3 使用 knife4j美化

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

3.1 使用方法

Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案。

官网:https://doc.xiaominfo.com/

首先,引用Knife4j的starter,Maven坐标如下:

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
	<version>4.1.0</version>
</dependency>

然后删除之前的springdoc-openapi-ui

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

3.2 常用配置项

官方说明地址:https://doc.xiaominfo.com/docs/features/enhance文章来源地址https://www.toymoban.com/news/detail-763176.html

## knife4j的增强配置,不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
    enable-home-custom: true
    home-custom-path: classpath:markdown/api-home.md
    enable-footer-custom: true
    footer-custom-content: 系统文档

到了这里,关于Spring Doc OpenAPI3.0 抛弃SpringFox拥抱SpringDoc的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 【springboot】Spring 官方抛弃了 Java 8!新idea如何创建java8项目

    我本来以为是 IDEA 版本更新导致的 Bug,开始还没在意。 直到我今天自己初始化项目时才发现:卧槽,Java 8 真没了?! 具体一点,应该是使用 IDEA 内置的 Spring Initializr 创建 Spring Boot 新项目时,没有 Java 8 的选项了,只剩下了 = 17 的版本 去网上搜了一圈,原来这是因为 Sprin

    2024年02月04日
    浏览(45)
  • Spring Boot 3.x 引入springdoc-openapi (内置Swagger UI、webmvc-api)

    接触的原因 因开发自己的项目时,写接口文档很繁琐,查到后端都在用 swagger 等接口工具来记录接口文档,于是学习了一下,本文记录个人配置过程,有问题欢迎指正交流😁 Swagger: Swagger是一种Rest API的表示方式,它是标准的、语言无关的工具,这种表示方式不仅人可读,

    2024年04月27日
    浏览(33)
  • @Tag和@Operation标签失效问题。SpringDoc 2.2.0(OpenApi 3)和Spring Boot 3.1.1集成

    问题 @Tag和@Operation标签失效 但是@Schema标签有效 pom依赖 debug排查,发现时国际化问题 解决方法:application.yml配置禁用i18n翻译

    2024年02月05日
    浏览(57)
  • Spring Security Oauth2.1 最新版 1.1.0 整合 gateway 完成授权认证(拥抱 springboot 3.1)

    目录 背景 demo地址 版本 Spring Boot 3.1 Spring Authorization Server 1.1.0 基础 spring security OAuth2 模块构成 授权方式 认证方式 集成过程 官方demo 代码集成 依赖 授权服务AuthorizationServerConfig配置 重要组件 测试 查看授权服务配置 访问授权服务 授权 回调 获取 access_token 获取用户信息 个性

    2024年02月08日
    浏览(64)
  • Spring Boot 集成 API 文档 - Swagger、Knife4J、Smart-Doc

    Swagger 作为 API 设计和文档的强大工具,是一个由专门的工具集合支持的框架,它在整个 API 的生命周期中发挥作用,从设计和文档,到测试和部署。通过提供可视化界面,Swagger 让开发人员和最终用户都能清晰地理解和操作 API。 使用建议:笔者建议优先考虑 Knife4J,它已经能

    2024年01月22日
    浏览(58)
  • 解决引入spire.doc.free-3.9.0.jar导致spring boot项目无法使用maven的install问题

    问题背景: 在一个项目中需求中需要导出一个word模板,那之前有做过一个这个类似需求,这次使用的是freemarker模版。在引入spire.doc.free-3.9.0.jar依赖的时候发现maven依赖报红色,悬浮提示aliyun找不到改包,没有太在意这个部分,本地能够正常使用。本地仓库存在这个jar包,并

    2024年02月15日
    浏览(52)
  • SpringBoot_springfox-swagger版本升级处理

    使用springfox-swagger2 + swagger-bootstrap-ui 升级实现2.7.0-2.10.5,发现高版本的配置方式与低版本配置存在差异,因此记录处理过程 maven依赖 Java Config maven依赖 Java Config 使用springfox-swagger2 + swagger-bootstrap-ui 升级实现2.7.0-2.10.5 需要改造 升级依赖版本 并补充springfox-spring-webmvc模块 注解启动

    2023年04月11日
    浏览(36)
  • springboot配置swagger3-springfox实现

    springfox 之前配置需要声明多个依赖,到了 3 直接声明一个 starter 就行了. springboot 版本 2.7.7 springfox-boot-starter 版本 3.0.0 声明依赖 声明yml配置 bean配置

    2024年02月12日
    浏览(36)
  • Springboot3.0整合swagger,废弃Springfox改用Springdoc

    Automated JSON API documentation for API\\\'s built with Spring 官网地址:springfox.io springdoc-openapi java library helps to automate the generation of API documentation using spring boot projects. 官网地址:https://springdoc.org/v2/ 注意 :使用的是V2版本,这个版本支持springboot3.0 之前springboot3.0之前我用的都是Springfox来集

    2023年04月09日
    浏览(44)
  • 抛弃Vuex,使用Pinia

    1.简介 官网 Pinia 起始于 2019 年 11 月左右的一次实验,其目的是设计一个拥有组合式 API 的 Vue 状态管理库。从那时起,我们就倾向于同时支持 Vue 2 和 Vue 3,并且不强制要求开发者使用组合式 API,我们的初心至今没有改变。除了 安装 和 SSR 两章之外,其余章节中提到的 API 均

    2024年02月06日
    浏览(40)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包