Skip to content

Latest commit

 

History

History
64 lines (41 loc) · 5.84 KB

create-openapi-specification.md

File metadata and controls

64 lines (41 loc) · 5.84 KB
Raw

Практическое занятие: Создание спецификации OpenAPI

В руководстве по OpenAPI мы прошли 8 этапов создания документа в спецификации OpenAPI. Теперь стоит попрактиковаться сначала в редактировании, а затем и в создании документа спецификации OpenAPI.

Содержание раздела

Практическое занятие: редакция существующего документа в спецификации OpenAPI

Создание документа в спецификации OpenAPI для выбранного API

👨‍💻 Практическое занятие: редакция существующего документа в спецификации OpenAPI

Используем простой API Sunrise and sunset times, чтобы лучше ознакомиться с процессом редактирования файла спецификации OpenAPI. API Sunrise and sunset times не требует аутентификации с запросами, поэтому здесь отсутствуют сложные рабочие процессы аутентификации (можно пропустить объект security). В этом упражнении мы отредактируем некоторые из существующих значений в уже написанном документе спецификации OpenAPI.

Для редактирования спецификации OpenAPI:

  1. Копируем код из предварительно созданной спецификации OpenAPI

  2. Вставляем содержимое YAML в редактор Swagger.

  3. Определяем каждый из объектов корневого уровня спецификации OpenAPI:

  1. В объекте info(в верхней части) внесите изменения в свойство description и посмотрите, как обновляется визуальный дисплей в правом столбце.
  2. В объекте parameters внесите изменения в одно из свойств описания и посмотрите, как обновляется визуальный редактор.
  3. Найдите указатель $ref в объекте response. Определите, на что он указывает в components.
  4. Измените несколько интервалов таким образом, чтобы сделать спецификацию недействительной (например, вставить пробел перед информацией), и посмотрите на появившуюся ошибку. Затем верните неверный пробел.
  5. Разверните раздел Get и нажмите Try it out. Затем нажмите Execute и посмотрите ответ.

👨‍💻 Создание документа в спецификации OpenAPI для выбранного API

На практике 3 модуля мы искали опен-сорс проект API, которому нужна была документация. Сейчас попробуем создать спецификацию OpenAPI для этого API. В зависимости от API, с которым мы решили работать, можно будет использовать этот документ как часть своего портфолио.

Если этот опен-сорс проект не имеет API или API уже имеет спецификацию OpenAPI, можно найти другой API (возможно, из этого списка из 100+ API) и создать спецификацию OpenAPI.

При создании спецификации пройдем по каждому шагу руководства по спецификации OpenAPI, чтобы создать документацию API:

После создания проверяем нашу документацию в редакторе Swagger. Выполним запрос, чтобы убедиться, что все работает верно.

🔙

Go next ➡