xml - 如何在 Swagger 文档中添加 xml 示例

Question

您好，我正在为 api 创建 swagger 文档，我想添加 xml 示例，但我做不到。

这是我写的 swagger 文档

swagger: "2.0"
info:
  title: Documentatie API 
  description: Descriere documentatie API metode POST
  version: 1.0.0
host: xxx.ro
basePath: /v1
schemes:
  - https
paths:
  /stareMesaj:
    post:
      summary: Stare mesaj
      description: Descriere stare mesaj
      consumes:

            - application/xml
      produces:

            - application/xml
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 4
              name:
                type: string
                example: Arthur Dent

我认为模式下的属性会在示例中进行转换，但它说:

<?xml version="1.0" encoding="UTF-8"?>
<!-- XML example cannot be generated; root element name is undefined -->

能给我举个例子吗？

提前致谢

Answer 1

您的内联架构没有名称，因此 Swagger UI 不知道如何在 XML 中命名根元素。

将 xml.name 添加到您的架构中:

      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              ...
            xml:           # <-----
              name: user

或者在definitions部分定义一个命名模式并引用它:

      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/user'

definitions:
  user:
    type: object
    properties:
      id:
        type: integer
        example: 4
      name:
        type: string
        example: Arthur Dent