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

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

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

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

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

• Копируем код из предварительно созданной спецификации OpenAPI
• Вставляем содержимое YAML в редактор Swagger.
• Определяем каждый из объектов корневого уровня спецификации OpenAPI:
  • Шаг 1: Объект openapi
  • Шаг 2: Объект info
  • Шаг 3: Объект servers
  • Шаг 4: объект paths
  • Шаг 5: Объект components
  • Шаг 6: Объект security
  • Шаг 7: Объект tags
  • Шаг 8: Объект externalDocs
• В объекте info(в верхней части) внесите изменения в свойство description и посмотрите, как обновляется визуальный дисплей в правом столбце.
• В объекте parameters внесите изменения в одно из свойств описания и посмотрите, как обновляется визуальный редактор.
• Найдите указатель $ref в объекте response. Определите, на что он указывает в components.
• Измените несколько интервалов таким образом, чтобы сделать спецификацию недействительной (например, вставить пробел перед информацией), и посмотрите на появившуюся ошибку. Затем верните неверный пробел.
• Разверните раздел Get и нажмите Try it out. Затем нажмите Execute и посмотрите ответ.

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

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

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

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

• Шаг 1: Объект openapi
• Шаг 2: Объект info
• Шаг 3: Объект servers
• Шаг 4: объект paths
• Шаг 5: Объект components
• Шаг 6: Объект security
• Шаг 7: Объект tags
• Шаг 8: Объект externalDocs

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

🔙

Go next ➡