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

Question

[Александр]

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

Дока пишется в гугл докс (так нужно), сервисы, вроде swagger не подходят.

Comments

[Александр]

Pardon Me! Where Do I Find 4giveness?, с докой гугла удобно работать в команде, дал ссылку, вместе что-то отридачили. По мне это удобнее.
В противном, можно и html страницу сверстать

[Владимир]

Александр, В команде удобно работать с гитом и автогенерацией в сваггер из кода, а гугл док это баловство.

[Виталий Хоменко]

А почему не Swagger? Это же на данный момент почти стандарт. Возможно вы просто не понимаете как его правильно использовать?

Answer 1

[Дмитрий Свиридов]

OpenAPI. Некоторые фреймворки умеют это генерить автоматически. Вот пример.

Answer 2

[Robur]

Дока пишется в гугл докс (так нужно), сервисы, вроде swagger не подходят.

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

Хотя если это вам надо для вашей внутренней бюрократии а не для пользы - то кто ж вам запретит. В таком случае в целом все равно как вы её будете оформлять и описывать, главное чтобы под эту бюрократию подходило.

Answer 3

[Игорь]

Например - Postman

Answer 4

[Владимир]

У нас в команде пользуемся вот этим. https://apidocjs.com/ не знаю насколько удобно писать в этом документацию, но пользоваться ей удобно. Я правда не уверен в том что эта тулза актуальная.

Answer 5

[mletov]

Например, в ASP.NET есть Swagger

Comments

[antonksa]

Да ладно. Как вам повезло. Думаю, может теперь на точька нэт перейти?

[Дмитрий Свиридов]

antonksa, .NET, ne nado))