如何使用枚举和格式导航大型 OpenAPI 架构

Question

我有一个需要查看和理解的大型 OpenApi 架构。也许我只是错过了一些东西，但Postman 或SwaggerUI 都没有让这变得容易。 classes ("type":"object"s) 处理正常 - 但其他关键元素没有显示其详细信息：

• formats 不显示
  • {"type":"string", "format":"uuid"} --> 只显示为{"type":"string"}
• enums 不显示它们的值，甚至不显示它是 enum '类型'。

“大”是指规范中的几千行yaml，几百种类型等。当然，可以直接导航yaml……但这完全否定了图形的目的界面，对于大型文档来说速度非常慢。

这是来自SwaggerUI 的屏幕截图。我希望AnEnum 模式表明它是一个枚举，它是一个值；而AClass.single_nested.a_list 是uuids 的列表......只有string 这没有帮助。邮递员也好不到哪里去；它生成示例数据，确实使用有效的 UUID 填充 uuids；但 enums 的值只是 ~lorem ipsum （即实际上无效，尽管 Postman 可以访问枚举值）

不喜欢文字墙，但这是生成此文字的 yaml。

components:
  schemas:
    AnEum:
      description: An enumeration.

              ###############
      enum:   ############### <- nothing useful is shown for enums
      - foo
      - bar
      title: AnEum
    AnotherClass:
      properties:
        a_list:
          items:
            type: string
            format: uuid
          title: A List
          type: array
      required:
      - a_list
      title: AnotherClass
      type: object
    AClass:
      properties:
        single_nested:
          $ref: '#/components/schemas/AnotherClass'
        an_enum:
          $ref: '#/components/schemas/AnEum'
        ## lots and lots
      required:
      - an_enum
      - single_nested
      title: AClass
      type: object
  securitySchemes:
    BearerTokenAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
info:
  description: 'dump a quick example'
  title: demo full schema 2
  version: 0.0.1
openapi: 3.0.2
paths:
  /api/v12345/somepath/{id_in_path}/:
    get:
      description: '...'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AClass'
          description: success
          ## lots and lots
      security:
      - BearerTokenAuth: []
      summary: none
    parameters:
    - description: the id_in_path as a UUID.
      in: path
      name: id_in_path
      required: true
      schema:

                        #########
        format: uuid    #########  <---  format not shown graphically
        type: string

任何以图形方式显示“完整”架构的图形工具都可以；主要的必要功能与 IDE 具有“go-to-definintion”的原因相同。 SwaggerUI 的“可扩展”格式化树也可以工作（如果有信息）

Answer 1

在 Swagger UI 架构视图中，format 显示在类型名称后面的括号中。例如type: string + format: uuid 显示为string($uuid)。

未显示的枚举值是 bug，它只影响没有显式 type 的枚举。此错误将在 Swagger UI/Editor 的下一版本中修复。解决方法是将type 添加到枚举中：

    AnEum:
      type: string   # <------------
      description: An enumeration.
      enum:
      - foo
      - bar
      title: AnEum