1. Введение
Спецификация OpenAPI (ранее спецификация Swagger) стандартизирует язык документации REST API и не зависит от платформы. Мы можем создавать документы OpenAPI в форматах YAML или JSON .
С другой стороны, Swagger — это набор инструментов для реализации и работы со стандартом. Некоторые из них бесплатны, некоторые с открытым исходным кодом, а некоторые являются коммерческими. Эти инструменты помогают нам проектировать, документировать и использовать REST API.
В этой статье мы узнаем, как форматировать текстовые описания в наших документах OpenAPI.
2. Редакторы OpenAPI
Несколько инструментов помогают нам в создании документов OpenAPI. Несколько популярных инструментов:
Несколько других редакторов поддерживают создание документов OpenAPI. Однако самым популярным и широко используемым редактором является Swagger Editor. Следовательно, мы узнаем о форматировании наших документов OpenAPI с помощью редактора Swagger.
3. Форматирование YAML и JSON
Документ OpenAPI представлен в формате JSON или YAML . Однако форматировать документацию при использовании YAML несложно.
Например, чтобы пометить слово или предложение как заголовок, мы используем приведенный ниже фрагмент кода в YAML:
description: |
# This is a heading in *italics*
This is in the next line
This is in **bold**
Представление YAML использует | (pipe) для представления скалярных литералов, которые могут быть многострочными.
Теперь давайте определим то же самое в JSON:
{
"description": "# This is a heading in *italics*\nThis is in the next line\n\nThis is in **bold**
}
Для сравнения, в представлении JSON escape-последовательности делают форматирование нелогичным. В дальнейшем мы будем рассматривать только методы форматирования документов спецификации OpenAPI, написанных на YAML.
Наконец, спецификация OpenAPI позволяет форматировать поля описания на всех уровнях. Таким образом, согласно спецификации, везде, где допустимо поле описания , мы можем его отформатировать, а поле описания соответствует стилю форматирования CommonMark .
Теперь давайте улучшим наши документы API, отформатировав их.
4. Заголовки
Подобно тому, как мы используем заголовки от <h1> до <h6> в HTML, мы можем использовать заголовки уценки, чтобы выделить текст. # представляет заголовок `` . Мы можем использовать # до шести уровней, чтобы подчеркнуть текст. Чем выше число # , тем меньше выделение текста.
Текст, за которым следует # , ярче и крупнее, чем текст, сопровождаемый ###### .
Например, рассмотрим YAML:
openapi: 3.0.1
info:
title: Petstore
description: |
# Pet Store APIs
## This is a sample Petstore server
### Contains APIs to manage the pet store
#### Note that the APIs support Basic Authentication and OAUTH
##### The samples contain Request and Response models
###### There are status codes defined as well
Swagger отображает текст как:
5. Выделение текста
Чтобы улучшить читабельность текста описания , мы можем выделить его жирным шрифтом или курсивом.
Размещение текста между ` и или между и ` делает текст жирным . Точно так же размещение текста внутри и или и сделает текст курсивом . Например, для YAML:
openapi: 3.0.1
info:
title: Petstore
description: |
## This document contains
**Pet Store APIs** *Note: All the APIs return application/json*.
__User APIs__ _Note: These APIs contain attachments and only support image/jpeg as the content type_
Swagger отображает YAML как:
6. Таблицы
Далее давайте посмотрим, как добавить таблицы в наши документы OpenAPI.
Существует ряд правил, которым необходимо следовать при отображении таблиц. Во-первых, каждый столбец в таблице должен начинаться и заканчиваться символом | (труба) символ. Во-вторых, разделите каждый из заголовков таблицы хотя бы одним символом – (дефис) . Однако максимальное количество – (дефис) не ограничено.
Например, давайте добавим таблицу для определения кодов состояния HTTP для нашего POST API:
paths:
/pet:
post:
tags:
- pet
description: |
**The below table defines the HTTP Status codes that this API may return**
| Status Code | Description | Reason |
| ---------------- | ------------| -----------------------------------|
| 201 | CREATED | If a pet is created successfuly. |
| 400 | BAD REQUEST | If the request is not valid. |
| 401 | UNAUTHORIZED| If the credentials are invalid. |
Сваггер генерирует:
7. Списки
Теперь давайте посмотрим, как отформатировать текст описания, чтобы он содержал списки.
7.1. Упорядоченный список
Элементы текста описания должны начинаться с числа, за которым следует . (период) . Однако порядок нумерации элементов значения не имеет. То есть фрагменты:
description: |
1. Available
3. Pending
1. Sold
description: |
1. Available
200. Pending
30. Sold
description: |
1. Available
100. Pending
50. Sold
генерировать тот же вывод:
1. Available
2. Pending
3. Sold
Нумерация элементов зависит от исходного элемента . Например, если мы начнем номер элемента с 10 , следующие элементы будут пронумерованы 11 , 12 , 13 и т. д. YAML ниже:
description: |
10. Available
120. Pending
50. Sold
генерирует:
10. Available
11. Pending
12. Sold
Точно так же те же правила применяются и к упорядоченным подспискам. Отступ подсписка к его родительскому элементу. В качестве примера рассмотрим YAML:
description: |
1. Available
2. Pending
1. Pending in Store
200. Pending in Cart
3. Sold
который генерирует:
1. Available
2. Pending
1. Pending in Store
2. Pending in Cart
3. Sold
7.2. Неупорядоченный список
Используйте * (звездочки) или + (плюс) или - (дефис) , чтобы создать ненумерованный список . То есть каждый элемент списка должен начинаться с одного из этих символов. Например:
description: |
* Available
* Pending
* Sold
description: |
+ Available
+ Pending
+ Sold
description: |
- Available
- Pending
- Sold
все приведенные выше фрагменты генерируют неупорядоченный список.
Точно так же, чтобы создать неупорядоченные подсписки, отступите элементы от их родительского элемента и начните с * (звездочки) или + (плюс) или - (дефис) . Например, YAML:
- Available
- Pending
* Pending in Store
+ Pending in Cart
- Sold
генерирует неупорядоченный список с подсписком. Обратите внимание на сочетание и соответствие разделителей. Можно смешивать разделители, что приводит к одинаковым результатам .
Наконец, давайте поместим все это вместе в YAML:
/pet/findByStatus:
get:
summary: Finds Pets by status
description: |
__Below is the list of valid status of the Pet__
1. Available
2. Pending
1. Pending in the cart
2. Pending in the store
3. Sold
**Below is the list of HTTP Status code this API may return**
* 200 - OK
* 400 - Bad Request. The API returns below status codes related to content-type and accept headers
+ 415 - Unsupported Media Type
- 406 - Not Acceptable
* 401 - Unauthorized
* 405 - Method not supported
Этот YAML генерирует:
8. Разное
8.1. Разрывы строк и абзацы
Затем, чтобы вставить разрыв строки, введите два пробела и клавишу возврата . Обратите внимание, что просто предоставление ключа возврата не выравнивает текст по следующей строке. Точно так же, чтобы вставить абзац, вставьте пустую строку.
Теперь давайте добавим к нашему описанию несколько разрывов строк и абзацев :
description: |
Returns a single pet.
*Note: The API may throw a HTTP 404 if there are no pets found with a given id.*
The API returns a 200 OK if there is a pet with given Id. Also, this API returns the status of the pet
Этот YAML генерирует:
8.2. Код
Далее давайте добавим немного кода в наш документ OpenAPI. Блоки кода начинаются и заканчиваются `символом «`` . Например, рассмотрим YAML :
description: |
The API returns user details for a given username.
The API can be invoked using *curl* like below:
curl --header accept: application/json -u username:password http://localhost:8080/api/v2/user/jhondoe
**Sample Output**
{ "id": 2, "username": "jhondoe" "email": "jhon.doe@mail.com" }
Приведенный выше YAML генерирует:
8.3. Картинки
Наконец, чтобы добавить изображение в документ, изображение должно быть добавлено к тексту описания в формате:
Swagger использует альтернативный текст , когда изображения не загружаются или когда мы наводим курсор на изображение. Также путь к изображению может быть абсолютным или относительным. Рассмотрим YAML:
description: |
# Pet Store APIs
Сваггер генерирует:
9. Заключение
В этой статье мы увидели, как форматировать поле описания в наших документах OpenAPI. Скалярные литералы YAML позволяют форматировать описание по всему документу. Следовательно, документ OpenAPI может содержать любую или все поддерживаемые конструкции, такие как списки, таблицы и изображения.
Таким образом, документирование API упрощает его использование. В конце концов, хорошо документированные и отформатированные API-интерфейсы — это то, что нам всем нужно для легкой интеграции и использования.