При знакомстве с REST API, было упомянуто, что REST API следуют архитектурному стилю, а не конкретному стандарту. Тем не менее, было разработано несколько спецификаций REST, чтобы попытаться представить стандарты в виде описания API REST. Вот три наиболее популярных спецификации REST API: OpenAPI (формально называется Swagger), RAML и API Blueprint.
В первые годы спецификаций между форматами существовала здоровая конкуренция. Но теперь, без сомнения, спецификация OpenAPI является самой популярной, с наибольшим сообществом, динамикой и различными инструментами. Из-за этого больше всего времени уделено OpenAPI в этом курсе. Фактически весь этот модуль посвящен спецификации OpenAPI. (RAML и API Blueprint размещены в модуле Глоссарий и источники в конце курса.)
Swagger относится к инструментам API, которые считывают и отображают информацию в спецификации. Подробный рассказ об OpenAPI и Swagger в следующих разделах.В целом, спецификации REST API приводят к улучшению структуры документации. Помните, что эти спецификации REST API в основном описывают эталонные конечные точки в API. Хотя эти разделы важны, помимо них необходима еще и иная документации. (Вот почему создан отдельный модуль концептуальные разделы API.)
Тем не менее, документация, которую покрывает спецификация, часто составляет основную ценность API, поскольку она касается конечных точек и их ответов.
Запись в спецификации вводит новое измерение в документацию, которое делает документацию API по существу уникальной. Овладев форматом спецификации OpenAPI, мы сможем значительно отличаться от других технических писателей.