Как оформить api доступ к данным, что бы было с ним комфортно работать?

Question

[Сергей Сунцев]

Доброе время суток!
Есть бибилиотека из http/https и wss/ws запросов (на node.js)
Делаю для своего сервиса открытый доступ к данным.
Доступ есть только на получение данных, т.е. на get запросы.

Как лучше всего их оформить для внешнего пользователя?

У меня в голове есть несколько вещей:
1) Сделать библиотеку на js, в ней уже собрать все методы для получения нужных данных, как к примеру библиотека у slack. И такую же аналогично и для php, python, go, java (на других языках к сожалению не работал)

2) Есть пример грамотно оформленной документации, и можно ли как то автоматически ее выгружать, на ум приходит только swagger, но мне способ его оформления не оч нравится, может кто то может посоветовать что по лучше?

3) За арихитектурный подход взял Rest, я понимаю, это вопрос холиварный, но тут вопрос в том, смогу ли я, если перейду на graphql, его автоматически документировать, как в swagger?

И последний вопрос - есть у кого то примеры ?
У какого сервиса самое приятно API с которым вы когда-либо работали?

Answer 1

[Владимир Коротенко]

чем плох сваггер?
а так оформите генерацию документации на основе комментов в коде, и у вас будет всегда актуальная документация. Если вы конечно не адепт самодокументированного кода.

Зачем вам graphql? У вас крутая аналитика и нужны сложны срезы?

Насчет оформления кода доступа. Напишите на чем можете, и главное добавьте примеры на чистом http, например как в яндексе, там вызов любого апи описан именно через запросы curl

Comments

[Сергей Сунцев]

подскажите, есть какой то инструментарий для оформления документации, через комментарии?

[Владимир Коротенко]

Сергей Сунцев, Все зависит от языка. Например в C# есть SoundCastle, в perl есть Pod.
В С, С++ по моему troff.

Сваггер что вы привели, но он больше для описания API.

Для js попробуйте это https://www.slant.co/topics/5104/~javascript-docum...
Но я не в курсе как работает.