Как я могу включить примеры API тела JSON в требования API Swagger2Markup (при конвертации из Swagger YAML)? - PullRequest
Новая
       17

Как я могу включить примеры API тела JSON в требования API Swagger2Markup (при конвертации из Swagger YAML)?

1 голос
/ 30 мая 2019

Я использовал редактор Swagger (editor.swagger.io) для создания требований API, которые отлично смотрятся в Интернете в веб-браузере, но я хочу преобразовать эту документацию Swagger YAML в формат, который можно распечатать (Word, PDF, Excel, HTML) и чтение в автономном режиме.

Единственный способ преобразовать Swamger YAML в чистый, пригодный для печати документ с требованиями API - это использовать CLI Swagger2Markup (вот справочная документация: http://swagger2markup.github.io/swagger2markup/1.3.3/ - Глава 8 описывает CLI), затем преобразует этот формат adoc в HTML из AsciiDoctor.Конечный продукт очень читабелен, как вы можете видеть из справочной документации Swagger2Markup.

Однако, к сожалению, , окончательная документация API Swagger2Markup не содержит JSON или XML-примеры API.кузов, который, пожалуй, самая важная часть документации на мой взгляд!Например, в зоомагазине редактора Swagger это будет пример тела json для API POST / pet: 

{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

Но этот пример JSON не включен в документацию Swagger2Markup.

Таким образом, мой вопрос, возможно ли обновить Swagger2Markup (или изменить свойства Swagger2Markup), чтобы включить Примеры API JSON body в окончательный документ?

Если нет, есть ли другой способвы рекомендуете конвертировать Swagger YAML в читаемый документ, включающий примеры JSON body API?

1 Ответ

1 голос
/ 31 мая 2019

Чтобы добавить примеры API json body в adoc с помощью swagger2markup, создайте файл конфигурации (config.properties) и добавьте «swagger2markup.generatedExamplesEnabled = TRUE».Согласно справочному документу swagger2markup, раздел 3.2.5, это свойство указывает, должны ли генерироваться примеры http rquest и response.Отлично!

...