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

Question

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

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

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

这是 SwaggerUI 的屏幕截图。我希望 AnEnum 模式显示它是一个枚举，它是值； AClass.single_nested.a_list 是 uuid 的列表...只有 string 它没有帮助。邮递员也好不了多少；它生成示例数据，确实用有效的UUID填充uuid；但是 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

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

how to navigate a large OpenAPI schema with enums and formats

api

swagger

postman

swagger-ui

openapi