Swagger：在哪里为调用提供示例 json？

Posted 2023-03-16

【中文标题】Swagger：在哪里为调用提供示例 json？

【英文标题】：Swagger: where to provide sample json for a call?

【发布时间】：2015-12-17 17:05:26

【问题描述】：

我是 Swagger 的新手，我正在尝试开始记录 API。我想在我的文档中包含请求/响应的示例，而不仅仅是架构定义本身。

响应对象上有一个“示例”功能，但是，当我填写此内容时，它不会显示在生成的文档中的任何位置。这只是暂时从 swagger 中缺少的功能，还是我错误地使用了此功能？

这是我的规范（我知道我还没有正确实现安全性）：

swagger: '2.0'
schemes: ['https']
info:
  version: 1.0.0.0
  title: 'Test API'
  contact:
    name: Support
    url: 'www.nowhere.com'
    email: '[e-mail]'
consumes: ['application/json']
produces: ['application/json']
paths:
  /Variables:
    get:
      summary: 
        Returns the list of all variables in the system.
      description:
        Returns the list of all variables in the system.
      tags: ['Variables']
      consumes: ['application/json']
      produces: ['application/json']
      parameters:
        - name: "Authorization"
          in: header
          description: "Provide the OAuth access token in the format of: Bearer token_value"
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/Variables'
          examples:
            application/json:
              VariableToken: Name
              VariableGroupName: Main
              DataType: text
              VariableDisplayName: Name
definitions:
  Variables:
    type: array
    items:
      title: Variable
      type: object
      properties:
        VariableToken:
          type: string
          format: string
        VariableGroupName:
          type: string
          format: string
        DataType:
          type: string
          format: string
        VariableDisplayName:
          type: string
          format: string

【问题讨论】：

我认为在您的示例部分中，您只需引用对象定义。另外，请帮自己一个忙，改用 JSON 风格的 swagger 声明。一旦您的定义文件变得很大，它会让生活变得更加轻松。

感谢您的反馈。我正在为尚不存在的 API 进行手动编辑，所以我正在用 YAML 编写，但是如果我愿意，swagger 编辑器会让我下载并转换为 json，所以我可以用任何一种格式表示。跨度>

是的，编辑器工作得很好，直到你的文件变大，然后它会变得非常缓慢。我选择在记事本中进行手动编辑，因为它很容易重新部署和检查更改。只是我学到的一个技巧！

谢谢。很高兴知道。您知道编辑器将您正在处理的文件存储在哪里吗？我似乎在 dist 文件夹中的任何地方都找不到它。我知道我可以将其导出并保存在本地，但我想知道 WIP 文件的位置。

另外，请注意，编辑器在 Preferences->Preferences 中有选项可禁用实时渲染和自动完成，旨在加快打字体验。

【参考方案1】：

我想通了。我将示例放在正确的位置，但是，Swagger Editor 不会在预览窗口中显示它。然而，Swagger UI 将生成带有此信息的 UI。