Whitelabel 错误页面：如何使用 Maven 在 YAML 文件中导出或打开 api 文档

Question

我已经使用 maven 在 java 中集成了 swagger UI，通过它我可以在 swagger UI 上测试我的 REST springBoot API 并且还能够看到使用 URL 以 json 格式打开 API 文档：http://localhost:8091/v2/api-docs?group=public-api . 但我的要求是以 yaml 格式获取该文档，为此我在下面点击 URL 但出现错误

http://localhost:8091/v3/api-docs.yaml

Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

Wed Mar 09 13:27:55 IST 2022
There was an unexpected error (type=Internal Server Error, status=500).
tried to access method com.fasterxml.jackson.databind.introspect.AnnotatedMember.getAllAnnotations()Lcom/fasterxml/jackson/databind/introspect/AnnotationMap; from class io.swagger.v3.core.jackson.ModelResolver

POM.xml中的条目是

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.javainuse</groupId>
    <artifactId>springboot-swagger-test</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.4.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>20.0</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-webmvc-core</artifactId>
            <version>1.6.6</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

我的招摇UI

Answer 1

你的 URL 有错字，应该是 http://localhost:8091/v2/api-docs.yaml

我从我这边测试过，它对我有用，它会下载 yaml 文件

Answer 2

在 POM.xml 中做了一些更改后，可以下载 .yaml 文件中的文档。

URL 下载 .yaml 文件中的文档是：http://localhost:8091/v3/api-docs.yaml

更新后的POM.xml是

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.javainuse</groupId>
    <artifactId>springboot-swagger-test</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.4</version>

    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>20.0</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-webmvc-core</artifactId>
            <version>1.6.6</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

示例生成的.yaml文件

openapi: 3.0.1
info:
  title: OpenAPI definition
  version: v0
servers:
- url: http://localhost:8099
  description: Generated server url
paths:
  /api/javainuse2:
    post:
      tags:
      - product-controller
      operationId: saveProduct
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
        required: true
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: string
  /api/javainuse:
    get:
      tags:
      - hello-controller
      operationId: sayHello
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: string
  /api/javainuse1:
    get:
      tags:
      - product-controller
      operationId: getProduct
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
  /swagger-resources:
    get:
      tags:
      - api-resource-controller
      operationId: swaggerResources_1
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    put:
      tags:
      - api-resource-controller
      operationId: swaggerResources
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    post:
      tags:
      - api-resource-controller
      operationId: swaggerResources_3
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    delete:
      tags:
      - api-resource-controller
      operationId: swaggerResources_4
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    options:
      tags:
      - api-resource-controller
      operationId: swaggerResources_2
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    head:
      tags:
      - api-resource-controller
      operationId: swaggerResources_6
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
    patch:
      tags:
      - api-resource-controller
      operationId: swaggerResources_5
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SwaggerResource'
  /swagger-resources/configuration/ui:
    get:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_1
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    put:
      tags:
      - api-resource-controller
      operationId: uiConfiguration
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    post:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_3
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    delete:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_4
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    options:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_2
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    head:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_6
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
    patch:
      tags:
      - api-resource-controller
      operationId: uiConfiguration_5
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/UiConfiguration'
  /swagger-resources/configuration/security:
    get:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_1
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    put:
      tags:
      - api-resource-controller
      operationId: securityConfiguration
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    post:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_3
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    delete:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_4
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    options:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_2
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    head:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_6
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
    patch:
      tags:
      - api-resource-controller
      operationId: securityConfiguration_5
      responses:
        "200":
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/SecurityConfiguration'
components:
  schemas:
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int32
        pname:
          type: string
        batchno:
          type: string
        price:
          type: number
          format: double
        noofproduct:
          type: integer
          format: int32
    SwaggerResource:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        swaggerVersion:
          type: string
        location:
          type: string
          deprecated: true
    UiConfiguration:
      type: object
      properties:
        deepLinking:
          type: boolean
        displayOperationId:
          type: boolean
        defaultModelsExpandDepth:
          type: integer
          format: int32
        defaultModelExpandDepth:
          type: integer
          format: int32
        defaultModelRendering:
          type: string
          enum:
          - example
          - model
        displayRequestDuration:
          type: boolean
        docExpansion:
          type: string
          enum:
          - none
          - list
          - full
        filter:
          type: object
        maxDisplayedTags:
          type: integer
          format: int32
        operationsSorter:
          type: string
          enum:
          - alpha
          - method
        showExtensions:
          type: boolean
        tagsSorter:
          type: string
          enum:
          - alpha
        validatorUrl:
          type: string
        apisSorter:
          type: string
          deprecated: true
        jsonEditor:
          type: boolean
          deprecated: true
        showRequestHeaders:
          type: boolean
          deprecated: true
        supportedSubmitMethods:
          type: array
          items:
            type: string
    SecurityConfiguration:
      type: object
      properties:
        apiKey:
          type: string
          deprecated: true
        apiKeyVehicle:
          type: string
          deprecated: true
        apiKeyName:
          type: string
          deprecated: true
        clientId:
          type: string
        clientSecret:
          type: string
        realm:
          type: string
        appName:
          type: string
        scopeSeparator:
          type: string
        additionalQueryStringParams:
          type: object
          additionalProperties:
            type: object
        useBasicAuthenticationWithAccessCodeGrant:
          type: boolean

Whitelabel 错误页面：如何使用 Maven 在 YAML 文件中导出或打开 api 文档

Whitelabel Error Page : How to export or open api doc in YAML file with maven

java

spring-boot

maven

swagger

openapi-generator