json - 用描述大摇大摆地转换 Json 响应

Question

我尝试使用 Swagger Editor 指定来自 GET 方法的响应。但是当我查看 Swagger UI 时，没有显示响应 JSON。

我的宣言大摇大摆：

 /clients/{id}:
get:
  consumes:
    - application/hal+json
  produces:
    - application/hal+json
  # This is array of GET operation parameters:
  parameters:
    # An example parameter that is in query and is required
    - name: id
      in: path
      required: true
      type: string

  # Expected responses for this operation:
  responses:
    # Response code
    200:
      description: Succes
      # A schema describing your response object.
      # Use JSON Schema format
      schema:
        example:
          application/json: |
            - {"produits":[{"idOffre":{"codeBanque":"038","identifiant":"123"},"idProduit":{"codeBanque":"061","identifiant":"123"}},{"idOffre":{"code":"038","identifiant":"123"},"idProduit":{"code":"061","identifiant":"123"}}]}
    .....

在 Swagger UI 中，写着 Response Class (Status 200) > Model Schema 的框有一个像这样的空 json -> {}

Answer 1

我不确定 swagger-ui 是否支持示例，但是我在您的 swagger 提取物中修复了一些错误：

• example重命名examples
• examples与缩进级别相同schema（在您的示例中，example作为响应模式的属性处理，我不确定这是您想要的）
• schema必须描述响应模型，完成 TODO

固定版本：

swagger: '2.0'
info:
  title: Clients
  description: API
  version: "1.0.0"
host: api.test.com
schemes:
  - https
basePath: /v1
produces:
  - application/json
paths:
  /clients/{id}:
    get:
      consumes:
        - application/hal+json
      produces:
        - application/hal+json
      parameters:
        - name: id
          in: path
          required: true
          type: string
      responses:
        200:
          description: Succes
          schema:
            type: array
            items:
              properties:
                produits:
                  type: string
                  description: TODO
          examples:
            application/json: |
                - {"produits":[{"idOffre":{"codeBanque":"038","identifiant":"123"},"idProduit":{"codeBanque":"061","identifiant":"123"}},{"idOffre":{"code":"038","identifiant":"123"},"idProduit":{"code":"061","identifiant":"123"}}]}