Spring Boot は springdoc-openapi を統合します

情報 2023-10-04 22:46:26 訪問数: null

オープンAPIの紹介

OpenApi は、業界の API ドキュメント標準および仕様です。

たとえば、Java の抽象概念は抽象クラスであり、API ドキュメントで標準化された抽象メソッドのみを提供します。

このメソッドは現在、2 つの主要な非公式実装によって実装されています。1 つは springfox で、もう 1 つは springdoc です。

威張った紹介

Swagger は API ドキュメント保守組織であり、後に Open API 標準の主要な定義者となり、最新バージョンは 2017 年にリリースされた Swagger3 (Open Api3) です。

springdoc の紹介

SpringDoc は、ユーザーが swagger3 を Spring に統合できるようにするために、Spring コミュニティによって維持されているプロジェクト (非公式) でもあります。これは、開発者が Spring でドキュメントを生成するのにも使用され、Spring Boot で簡単に使用できます。

この組織のプロジェクトは、Swagger ページの Oauth2 ログイン (Open API3 の内容) をサポートしており、Springfox と比較するとサポート期間が長く、間違いなく優れた選択肢です。

springdoc-openapi は、実行時にアプリケーションを検査し、Spring 構成、クラス構造、およびさまざまなアノテーションに基づいて API セマンティクスを推論することによって機能します。JSON/YAML および HTML 形式の API でドキュメントを自動的に生成します。このドキュメントは、Swagger API アノテーションを使用してアノテーションを使用して実行できます。

springdoc-openapi ライブラリは以下をサポートしています。

  • オープンAPI 3
  • スプリングブート (v1 および v2)
  • JSR-303、特に @NotNull、@Min、@Max、および @Size 用。Swagger-ui
  • OAuth2

統合利用

springdoc-openapi-uiMaven プロジェクトに依存関係を導入します。

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

Springfox と springdoc アノテーションのマッピング関係:

@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @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")

application.yml 設定ファイルのリファレンス:

spring:
  application:
    name: springdoc-openapi
server:
  port: 8080

# ===== SpringDoc配置 =====#
springdoc:
  swagger-ui:
    # 自定义的文档界面访问路径。默认访问路径是/swagger-ui.html
    path: /springdoc/docs.html

    # 字符串类型，一共三个值来控制操作和标记的默认展开设置。它可以是“list”（仅展开标记）、“full”（展开标记和操作）或“none”（不展开任何内容）。
    docExpansion: none

    # 布尔值。控制“试用”请求的请求持续时间（毫秒）的显示。
    displayRequestDuration: true

    # 布尔值。控制供应商扩展（x-）字段和操作、参数和架构值的显示。
    showExtensions: true

    # 布尔值。控制参数的扩展名（pattern、maxLength、minLength、maximum、minminimum）字段和值的显示。
    showCommonExtensions: true

    # 布尔值。禁用swagger用户界面默认petstore url。（从v1.4.1开始提供）。
    disable-swagger-default-url: true

  api-docs:
    # enabled the /v3/api-docs endpoint
    enabled: true

    # 自定义的文档api元数据访问路径。默认访问路径是/v3/api-docs
    path: /springdoc/api-docs

    # 布尔值。在@Schema（名称name、标题title和说明description，三个属性）上启用属性解析程序。
    resolve-schema-properties: true

  # 布尔值。实现OpenApi规范的打印。
  writer-with-default-pretty-printer: true

# ===== swagger配置 =====#
swagger:
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: springdoc openapi整合Demo
  try-host: http://localhost:${server.port}

Swagger 構成クラス:

@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {
    /**
     * 项目应用名
     */
    private String applicationName;

    /**
     * 项目版本信息
     */
    private String applicationVersion;

    /**
     * 项目描述信息
     */
    private String applicationDescription;

    /**
     * 接口调试地址
     */
    private String tryHost;

    public String getApplicationName() {
        return applicationName;
    }

    public void setApplicationName(String applicationName) {
        this.applicationName = applicationName;
    }

    public String getApplicationVersion() {
        return applicationVersion;
    }

    public void setApplicationVersion(String applicationVersion) {
        this.applicationVersion = applicationVersion;
    }

    public String getApplicationDescription() {
        return applicationDescription;
    }

    public void setApplicationDescription(String applicationDescription) {
        this.applicationDescription = applicationDescription;
    }

    public String getTryHost() {
        return tryHost;
    }

    public void setTryHost(String tryHost) {
        this.tryHost = tryHost;
    }
}

完全かつ詳細な springdoc openapi 構成例:

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.headers.Header;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.servers.Server;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.lang.reflect.Field;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Configuration
public class SpringdocOpenapiConfiguration implements WebMvcConfigurer {

    private final SwaggerProperties swaggerProperties;

    public SpringdocOpenapiConfiguration(SwaggerProperties swaggerProperties) {
        this.swaggerProperties = swaggerProperties;
    }

    @Bean
    public OpenAPI springDocOpenAPI() {
        //配置认证、请求头参数
        Components components = new Components();
        Map<String, Object> myHeader2extensions = new HashMap<>(2);
        myHeader2extensions.put("name", "myHeader2");
        components
                .addSecuritySchemes("bearer-key", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))
                .addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
                .addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1"))
                //注：这种方式有问题，不推荐
                .addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema()).extensions(myHeader2extensions))
                .addParameters("myGlobalHeader", new HeaderParameter().required(true).name("My-Global-Header").description("My Global Header").schema(new StringSchema()).required(false))
        ;

        // 接口调试路径
        Server tryServer = new Server();
        tryServer.setUrl(swaggerProperties.getTryHost());

        return new OpenAPI()
                .components(components)
                .servers(Collections.singletonList(tryServer))
                .info(new Info()
                        .title(swaggerProperties.getApplicationName() + " Api Doc")
                        .description(swaggerProperties.getApplicationDescription())
                        .version("Application Version: " + swaggerProperties.getApplicationVersion() + "\n Spring Boot Version: " + SpringBootVersion.getVersion())
                        .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))
                )
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Full Documentation")
                        .url("https://springdoc.org/")
                );
    }

    /**
     * 添加全局的请求头参数
     */
    @Bean
    public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
        return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
                .forEach(operation -> {
                    operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myGlobalHeader"));
                });
    }

    /**
     * 通用拦截器排除设置，所有拦截器都会自动加springdoc-opapi相关的资源排除信息，不用在应用程序自身拦截器定义的地方去添加，算是良心解耦实现。
     */
    @SuppressWarnings("unchecked")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration.excludePathPatterns("/springdoc**/**");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

例

プロジェクトのデモ: springdoc-openapi

レンダリング：

例
例

参考

おすすめ

転載: blog.csdn.net/qq_41787812/article/details/128627748
おすすめ
ランキング
Python 描画 3D 動的ヒストグラム コード チュートリアル
[vue3 共通エラー 5] Uncaught (in Promise) TypeError: xxx は関数ではありません
シンプルアップロードExcelファイルやデータベースにデータを追加
springboot における import アノテーションの役割
numpy 多维矩阵的维度交换
WMS システム - ウェーブ管理
Redis（7）マスター/スレーブレプリケーション
三北斗七星星座コアグローバルシステムの導入は完了です！グローバルネットワークを推進するために、
sql server语法——排序查询
続行することはできません立ち往生
アーカイブ
もっと
2024-05-16(24)
2024-05-15(5)
2024-05-14(9)
2024-05-13(8)
2024-05-12(27)
2024-05-11(31)
2024-05-10(33)
2024-05-09(30)
2024-05-08(18)
2024-05-07(34)

コードワールド

© 2018 codetd.com