Моя команда и я пишем несколько REST API, и мы хотели бы создать качественную, отточенную API-документацию для наших потенциальных клиентов. Я ищу какую-то платформу, которая могла бы поддерживать следующее:
- Допускает фоновую / сопутствующую информацию об API
- Позволяет в примерах использования / пользовательских историях описывать логическую последовательность вызовов API в различных сценариях
- Позволяет вставлять изображения или видео для примеров и демонстраций.
- Поддерживает Open API 2.0 или 3.0 для технической документации
- Позволяет настраивать стили для брендинга
Мы создавали и поддерживали документацию Swagger 2.0 для наших API, поэтому мы уже рассмотрели это. Мы использовали Swagger UI внутри, чтобы наши разработчики внешнего интерфейса могли противостоять. Это было здорово для технической документации, но я чувствую, что Swagger не поддерживает много фоновой, пользовательской истории, которую я также хотел бы включить (возможно, я просто недостаточно хорошо знаю спецификацию).
Я изучил некоторые другие платформы документации API, основанные на спецификациях Swagger / Open API. Проблема, которую я нахожу, состоит в том, что многие из них основаны исключительно на спецификации. Это означает, что все описания введения / пользовательской истории помещаются в поля «информация» или «описание» в уценке. Который, я думаю, делает трюк, но он кажется мне немного хакерским.
Желательно, чтобы я мог импортировать технические аспекты документации из моего файла Swagger и управлять любым дополнительным контентом через платформу. Любые предложения будут ценны.