Какие способы документирования API вы знаете и как документировали свой сервис?

Для HTTP API используют OpenAPI, описания сценариев и примеры запросов; для событийных интерфейсов — схемы сообщений и документацию каналов, например AsyncAPI.

В контракте фиксируют операции, параметры, схемы данных, авторизацию, ошибки и правила совместимости. Примеры должны показывать не только успешный ответ, но и типовые отказы. Swagger UI — один из способов отображения OpenAPI, а не отдельная замена контракту. В рассказе о своём сервисе поясните, где хранится описание и как проверяется его соответствие реализации.