Jurik-Phys.Net

RESTful API — это интерфейсы, используемые двумя компьютерными системами для безопасного обмена информацией через Интернет.

The OpenAPI Specification (OpenAPI) является спецификацией для описания REST API.

Создание спецификации OpenAPI - практическое занятие из большого курса по документированию REST API, который является переводом курса Documenting APIs: a guide for technical writers технического писателя Amazon, Тома Джонсона.

Qt and OpenAPI/Swagger – a tutorial (2021)

• video report;
• pdf preseitation.

Видео с созданием REST API с нуля - подробное описание создания OpenAPI спецификации со всеми основными методами.

Swagger Editor - онлайн сервис, предназначенный для разработки и редактирования файлов спецификации OpenAPI в форматах JSON или YAML.

OpenAPI Generator - это инструмент, который позволяет автоматически генерировать клиентский и серверный код на различных языках программирования на основе спецификации API, описанной в формате OpenAPI, форк Swagger Codegen, поддерживающий гораздо большее число вариантов генерации кода, чем исходный проект.

Сonverter YAML to JSON позволяет создавать тестовые выборки данных, хранящихся в JSON-файлах.

1. Создание спецификаци OpanAPI и сохранение её в JSON-формате: Swagger Editor.

2. Генерация клиента и сервера на основе полученного JSON-файла: предлагаемый bash-скрипт.

3. Настройка:

• браузер с запущенным Swagger Editor'ом будет блокировать ответы backend-сервера с адресом, отличным от адреса браузера. Причина - механизм безопасности CORS (Cross-Origin Resource Sharing). Решение состоит в добавлении в заголовки ответа сервера строки

  "Access-Control-Allow-Origin" : "*"

• для обработки POST запроса содержащим в заголовке

  Access-Control-Request-Method: POST
  Access-Control-Request-Headers: Content-Type

  сервер должен разрешать соответствующую обработку, что делается добавлением на стороне сервера следующих данных в заголовок ответа на POST-запрос

  Access-Control-Allow-Headers: Authorization, Content-Type
  Access-Control-Allow-Methods: GET,PUT,POST,DELETE,PATCH,OPTIONS

  Здесь обязательным являются значения «Content-Type» и «OPTIONS».

• если Swagger Editor использует защищённый протокол https, а в json-файле указана схема http, то запросы браузера к backend-серверу будут блокироваться браузером с пометкой Mixed Content . Решение на время разработки состоит в том, чтобы установить локальный Swagger Editor и обращаться к baсkend-серверу по http.