AleksandrB
@AleksandrB
Совсем недавно вывел "Hello world"

Как оформлять документацию для REST api?

Пишу документацию для restfull api, задался вопросом о правильности. Существуют ли стандарты оформления, например, информации о запросе. Было бы неплохо увидеть примеры.

Дока пишется в гугл докс (так нужно), сервисы, вроде swagger не подходят.
  • Вопрос задан
  • 1344 просмотра
Пригласить эксперта
Ответы на вопрос 5
@dimuska139
Backend developer
OpenAPI. Некоторые фреймворки умеют это генерить автоматически. Вот пример.
Ответ написан
Robur
@Robur
Знаю больше чем это необходимо
Дока пишется в гугл докс (так нужно), сервисы, вроде swagger не подходят.


генерите нормальным сервисом, потом копипастите в гуглодоки если вам так надо. Можно как-то автоматизировать.
Писать доки к апи руками - это не только мартышкин труд но и постоянная проблема актуализации - несколько раз будет проблемы из-за того что в доке что-то не соответствует реальности и она потеряет свой авторитет, а соответственно и полезность.

Хотя если это вам надо для вашей внутренней бюрократии а не для пользы - то кто ж вам запретит. В таком случае в целом все равно как вы её будете оформлять и описывать, главное чтобы под эту бюрократию подходило.
Ответ написан
У нас в команде пользуемся вот этим. https://apidocjs.com/ не знаю насколько удобно писать в этом документацию, но пользоваться ей удобно. Я правда не уверен в том что эта тулза актуальная.
Ответ написан
@mletov
Например, в ASP.NET есть Swagger
Ответ написан
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы