如何将 Springdoc Swagger UI 指向我自己的 YAML 文件而不是自动生成的文件？

Question

我创建了一个 Spring Boot RESTFul 微服务，对于文档，我创建了一个 swagger.yaml 文件，但我不知道如何运行该文件。为了创建 swagger.yaml 文件，我使用了 OpenAPI 规范。我知道我们有一个 Swagger UI 功能可以使用，但我想运行我自己创建的 swagger.yaml 文件，只是为了摆脱大量注释。

openapi: 3.0.1

info:
title: Static Data Manager
description: This is Static data Manager Swagger
version: 1.0.0

servers:
- url: http://localhost:8184/
  description: Generated server url

tags:
- name: LookupController
  description: API of Lookups
- name: LookupDataController
  description: API of Lookups Data
- name: LookupLangController
  description: API of Lookups Lang
- name: TranslationController
  description: API of Translations

paths:
/translation:
get:
  tags:
    - TranslationController
  operationId: fetchAll
  summary: Get All Translations
  parameters:
    - name: text
      in: query
      required: false
      schema:
        type: string
    - name: code
      in: query
      required: false
      schema:
        type: string
    - name: lang
      in: query
      required: false
      schema:
        type: string
    - name: pageable
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/Pageable'
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageTranslationModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
put:
  tags:
    - TranslationController
  operationId: update
  summary: Update a Translation
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/TranslationModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TranslationModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
post:
  tags:
    - TranslationController
  operationId: save
  summary: Save a Translations
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/TranslationModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TranslationModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
/translation/{transId}:
get:
  tags:
    - TranslationController
  operationId: fetch
  summary: Fetch a Translation
  parameters:
    - name: transId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TranslationModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
delete:
  tags:
    - TranslationController
  operationId: delete
  summary: Delete a Translation
  parameters:
    - name: transId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            type: object
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input

/lookupsLang:
get:
  tags:
    - LookupLangController
  operationId: fetchAll_1
  summary: Get All Lookup Langs
  parameters:
    - name: text
      in: query
      required: false
      schema:
        type: string
    - name: lang
      in: query
      required: false
      schema:
        type: string
    - name: sorting
      in: query
      required: false
      schema:
        type: string
    - name: pageable
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/Pageable'
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageLookupLangModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
put:
  tags:
    - LookupLangController
  operationId: update_1
  summary: Update a Lookup Lang
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupLangModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupLangModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
post:
  tags:
    - LookupLangController
  operationId: save_1
  summary: Save a Lookup Lang
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupLangModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupLangModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
/lookupsLang/{lookupId}:
get:
  tags:
    - LookupLangController
  operationId: fetch_1
  summary: Fetch a Lookup Lang
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupLangModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
delete:
  tags:
    - LookupLangController
  operationId: delete_1
  summary: Delete a Lookup Lang
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            type: object
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input

/lookupsData:
get:
  tags:
    - LookupDataController
  operationId: fetchAll_2
  summary: Get All Lookups Data
  parameters:
    - name: text
      in: query
      required: false
      schema:
        type: string
    - name: code
      in: query
      required: false
      schema:
        type: string
    - name: pageable
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/Pageable'
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageLookupDataModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
put:
  tags:
    - LookupDataController
  operationId: update_2
  summary: Update a Lookup Data
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupDataModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupDataModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
post:
  tags:
    - LookupDataController
  operationId: save_2
  summary: Save a Lookup Data
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupDataModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupDataModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
/lookupsData/{lookupId}:
get:
  tags:
    - LookupDataController
  operationId: fetch_2
  summary: Fetch a Lookup Data
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupDataModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
delete:
  tags:
    - LookupDataController
  operationId: delete_2
  summary: Delete a Lookup Data
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            type: object
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input

/lookups:
get:
  tags:
    - LookupController
  operationId: fetchAll_3
  summary: Get All Lookups
  parameters:
    - name: lookupName
      in: query
      required: false
      schema:
        type: string
    - name: text
      in: query
      required: false
      schema:
        type: string
    - name: code
      in: query
      required: false
      schema:
        type: string
    - name: pageable
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/Pageable'
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageLookupModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
put:
  tags:
    - LookupController
  operationId: update_3
  summary: Update a Lookup
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
post:
  tags:
    - LookupController
  operationId: save_3
  summary: Save a Lookup
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/LookupModel'
    required: true
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
/lookups/{lookupId}:
get:
  tags:
    - LookupController
  operationId: fetch_3
  summary: Fetch a Lookup
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LookupModel'
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input
delete:
  tags:
    - LookupController
  operationId: delete_3
  summary: Delete a Lookup
  parameters:
    - name: lookupId
      in: path
      required: true
      schema:
        type: integer
        format: int64
  responses:
    "200":
      description: OK
      content:
        application/json:
          schema:
            type: object
    '401':
      description: Unauthorised
    '403':
      description: Forbidden
    '404':
      description: Invalid input

 components:
  schemas:
  TranslationModel:
    type: object
    properties:
      webId:
        type: integer
        format: int64
      clientId:
        type: integer
        format: int64
      text:
        type: string
      code:
        type: string
      lang:
        type: string
  LookupLangModel:
  type: object
  properties:
    webId:
      type: integer
      format: int64
    lookupDataId:
      type: integer
      format: int64
    clientId:
      type: integer
      format: int64
    text:
      type: string
    lang:
      type: string
    sorting:
      type: integer
      format: int32
LookupDataModel:
  type: object
  properties:
    webId:
      type: integer
      format: int64
    clientId:
      type: integer
      format: int64
    lookupId:
      type: integer
      format: int64
    startDate:
      type: string
      format: date-time
    endDate:
      type: string
      format: date-time
    description:
      type: string
    text:
      type: string
    code:
      type: string
    lookupName:
      type: string
    sorting:
      type: integer
      format: int32
    strAttribute1:
      type: string
    strAttribute2:
      type: string
    strAttribute3:
      type: string
    intAttribute1:
      type: integer
      format: int32
    intAttribute2:
      type: integer
      format: int32
    intAttribute3:
      type: integer
      format: int32
    status:
      type: integer
      format: int32
    lookupLangModels:
      type: array
      items:
        $ref: '#/components/schemas/LookupLangModel'
LookupModel:
  type: object
  properties:
    webId:
      type: integer
      format: int64
    clientId:
      type: integer
      format: int64
    startDate:
      type: string
      format: date-time
    endDate:
      type: string
      format: date-time
    lookupName:
      type: string
    status:
      type: integer
      format: int32
    lookupDataModels:
      type: array
      items:
        $ref: '#/components/schemas/LookupDataModel'
Pageable:
  type: object
  properties:
    offset:
      type: integer
      format: int64
    sort:
      $ref: '#/components/schemas/Sort'
    unpaged:
      type: boolean
    paged:
      type: boolean
    pageSize:
      type: integer
      format: int32
    pageNumber:
      type: integer
      format: int32
Sort:
  type: object
  properties:
    unsorted:
      type: boolean
    sorted:
      type: boolean
    empty:
      type: boolean
PageTranslationModel:
  type: object
  properties:
    totalPages:
      type: integer
      format: int32
    totalElements:
      type: integer
      format: int64
    size:
      type: integer
      format: int32
    content:
      type: array
      items:
        $ref: '#/components/schemas/TranslationModel'
    number:
      type: integer
      format: int32
    sort:
      $ref: '#/components/schemas/Sort'
    numberOfElements:
      type: integer
      format: int32
    first:
      type: boolean
    last:
      type: boolean
    pageable:
      $ref: '#/components/schemas/Pageable'
    empty:
      type: boolean
PageLookupLangModel:
  type: object
  properties:
    totalPages:
      type: integer
      format: int32
    totalElements:
      type: integer
      format: int64
    size:
      type: integer
      format: int32
    content:
      type: array
      items:
        $ref: '#/components/schemas/LookupLangModel'
    number:
      type: integer
      format: int32
    sort:
      $ref: '#/components/schemas/Sort'
    numberOfElements:
      type: integer
      format: int32
    first:
      type: boolean
    last:
      type: boolean
    pageable:
      $ref: '#/components/schemas/Pageable'
    empty:
      type: boolean
PageLookupDataModel:
  type: object
  properties:
    totalPages:
      type: integer
      format: int32
    totalElements:
      type: integer
      format: int64
    size:
      type: integer
      format: int32
    content:
      type: array
      items:
        $ref: '#/components/schemas/LookupDataModel'
    number:
      type: integer
      format: int32
    sort:
      $ref: '#/components/schemas/Sort'
    numberOfElements:
      type: integer
      format: int32
    first:
      type: boolean
    last:
      type: boolean
    pageable:
      $ref: '#/components/schemas/Pageable'
    empty:
      type: boolean
PageLookupModel:
  type: object
  properties:
    totalPages:
      type: integer
      format: int32
    totalElements:
      type: integer
      format: int64
    size:
      type: integer
      format: int32
    content:
      type: array
      items:
        $ref: '#/components/schemas/LookupModel'
    number:
      type: integer
      format: int32
    sort:
      $ref: '#/components/schemas/Sort'
    numberOfElements:
      type: integer
      format: int32
    first:
      type: boolean
    last:
      type: boolean
    pageable:
      $ref: '#/components/schemas/Pageable'
    empty:
      type: boolean

Answer 1

确保您的自定义 yaml/json 文件保存在 resources/static 文件夹下。 然后将

springdoc.swagger-ui.url

属性设置为您的文件名。

示例

结构：资源 -> 静态 -> swagger-config.yaml

属性：

springdoc.swagger-ui.url=/swagger-config.yaml

Answer 2

如果您使用

springdoc-openapi-starter-webflux-ui

依赖项并且 springdoc 推荐不起作用，请确保静态文件可提供服务。下面是解决此问题的方法之一。

@Bean
RouterFunction<ServerResponse> staticResourceRouter(){
     return RouterFunctions.resources("/**", new ClassPathResource("static/"));
}