Кой е най-добрият инструмент за документиране/генериране на справка за RESTful/HTTP RPC API? [затворено]

Много въпроси бяха публикувани и отговориха на REST / HTTP базирани API и т.н., но никой не изглежда да разполага с много информация по следния въпрос:

Какви инструменти са налични/използвани за документиране на HTTP-RPC API? Кои инструменти са най-добрите?

Подобен въпрос (специфичен за ASP.NET) от януари 2009 г. може да бъде намерен тук, но без отговори.

В процес съм на разработване на няколко приложни програмни интерфейса (API) както професионално, така и за лични проекти (.NET MVC/OpenRasta, PHP, Coldfusion и т.н.) и не намерих нищо конкретно, което да помогне за документирането на тези API. Не търся автоматично генериране въз основа на анализиране на код/изчистване или нещо подобно. Както вероятно вече знаете, RESTful/HTTP-базираният API трябва да бъде независим от клиента и платформата; като такъв бих очаквал всеки инструмент за документиране да бъде същият.

Характеристики, които един приличен инструмент може да има:

  • Посочете формат/структура на URL/URI
  • Формати и методи за заявка/отговор (GET/POST/и т.н., XML/JSON/и т.н.)
  • Категоризирайте крайни точки/API повиквания (като групиране на няколко повиквания под Удостоверяване)
  • Автоматично генериране на статични референтни файлове/документация като примерите по-долу
  • Включете примери, тестови случаи и др

Ето няколко примера за това, което считам за прилична документация/референция(и) на API:

http://dev.twitter.com/doc/post/statuses/destroy/:id

http://www.salesforce.com/us/developer/docs/api_rest/index.htm

http://www.flickr.com/services/api/


api rest documentation-generation
person Colin    schedule 06.06.2011    source източник
comment
lunatech-labs.com/open-source/jax-doclets изглежда обещаващо, но аз самият не съм го използвал. Освен това е специфичен за Java, въпреки че може би идеите зад него ще бъдат пренесени на други езици...   -  person MatrixFrog    schedule 06.06.2011
comment
Щеше да е страхотно, ако използвах Java :P Въпреки това, определено би било полезно за бъдещи java проекти, така че благодаря за връзката!   -  person Colin    schedule 06.06.2011
comment
Създадох прост шаблон за RESTful API документация: github.com/berb/rest-doc-template Може би е полезно и за вас. Ако не, може да искате да разклоните и да го използвате като основа.   -  person b_erb    schedule 19.06.2011
comment
Друг чудесен пример за RESTful API документация: twilio.com/docs/api/rest/call   -  person Nikola Petkanski    schedule 11.02.2013
comment
статия за някои опции: apievangelist .com/2014/01/16/   -  person JasonS    schedule 03.07.2014

Отговори (4)


arrow_upward
8
arrow_downward

SWAGGER вероятно си заслужава да разгледате, ако имате нужда. Използвам го за документиране на REST входни точки, изложени от java приложение, използващо Jersey, но изглежда, че можете да го използвате и с други езици.

person Michael Zilbermann    schedule 11.02.2013
comment
Това е почти това, което търсих. Благодаря :) - person Colin; 12.02.2013

arrow_upward
3
arrow_downward

Една от причините, поради които такъв инструмент не съществува, е, че документацията на RESTful API НЕ трябва да включва нито един от тези елементи:

  • Посочете формат/структура на URL/URI
  • Формати и методи за заявка/отговор (GET/POST/и т.н., XML/JSON/и т.н.)
  • Категоризирайте крайни точки/API повиквания (като групиране на няколко повиквания под Удостоверяване)

RESTful API документацията е за документиране на използваните типове медии и свързаната с тях семантика на приложението. Трябва да търсите да създадете нещо, което прилича повече на това.

Примерите, които сте дали, са базирани на HTTP RPC API, поради което изискват този тип документация за крайни точки. Те са RESTful само по име. Защо хората не създават инструменти за автоматично документиране на HTTP базирани RPC API, не мога да ви кажа. Може би защото хората, които пишат тези API, са толкова заети да ги поддържат, че нямат време да пишат инструменти за документация!

person Darrel Miller    schedule 06.06.2011
comment
Разбирам, че посочвате, и не искам да споря за семантиката, например en.wikipedia.org/wiki /Restful е доста подвеждащ по темата. Лично аз бих разграничил RESTful приложение и RESTful API като две различни единици. Въпреки това, в интерес на здравия разум, ще актуализирам въпроса си, за да бъда по-конкретен! - person Colin; 06.06.2011
comment
-1: Догматични удари над практичността. REST API също се нуждаят от документация. Кои HTTP кодове за състояние се очаква да получа за целите на проверката? Как се обработва удостоверяването? Кой набор от знаци трябва да използвам? Как изглежда полезният товар? Има ли части от него по избор? Какъв вид данни приемат отделните компоненти? Забелязвате, че тези неща, като семантика на приложението, си струва да бъдат документирани, но изглежда отричате, че трябва да съществува инструмент, който може да се използва за лесно документиране на това, приемайки, че вместо това означава, че съществуването на инструмент означава, че сте избрали грешно решение. - person Jesper; 11.02.2013
comment
@jesper Код на състоянието за целите на валидирането: 400. Удостоверяването се обработва, въпреки че заглавката на www-authenticate го казва. Или типът медия, или връзката на връзката ще ви кажат как изглежда полезният товар. Charset? тип медии документи. Незадължителни компоненти, документи за тип носител. Ако инструмент може магически да го документира, тогава има вероятност да се окажете с документи, които казват GET /Customer за извличане на клиент. Което IMHO е 100% излишно. В система RESTful откриването на ресурси трябва да бъде динамично, а не в документация. - person Darrel Miller; 11.02.2013
comment
@DarrelMiller: Сигурно говорите за различен вид REST API. API на Twitter документира всичко това. Напълно съм съгласен, че псевдодокументация като тази е напълно безполезна. Това обаче не беше първоначалният въпрос; беше как да прикрепя обоснована документация към моя списък с повиквания, който в контекст на REST ще бъде списък с ресурси и разрешени операции. REST не се ограничава до HATEOAS, където вашите точки са много по-приложими. - person Jesper; 11.02.2013
comment
@Jesper REST не се ограничава до HATEOAS. Очевидно човекът, който е измислил термина, не е съгласен: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven - person Darrel Miller; 11.02.2013
comment
@DarrelMiller: Знам какво казва тезата на Рой Филдинг (и какво казва Рой Филдинг като цяло). Също така знам какво правят повечето (самоозначени) REST API, които се използват. Не казвам, че не очаквам с нетърпение бъдещето му, но то все още не е тук, а междувременно всички ние трябва да се справяме със системите около нас, които наистина съществуват. - person Jesper; 11.02.2013

arrow_upward
0
arrow_downward

След много проучвания открих, че това не е инструмент, който прави точно това, което искам. Има редица инструменти, които до голяма степен са стъпка в правилната посока, но често са специфични за езика и не генерират референтна документация за HTTP API/RPC, а по-скоро референтна документация за код/библиотека/API.

В резултат на това планирам да създам инструмента, който изисквам/предвидя от нулата. Ако/когато имам какво да покажа, ще актуализирам отговора си.

person Colin    schedule 23.06.2011
comment
някакви актуализации за създаването на този инструмент? - person rtdp; 18.02.2012
comment
Създадох спецификации за инструмента и схема за данни, но за съжаление все още не съм започнал да го изграждам. - person Colin; 07.03.2012

arrow_upward
0
arrow_downward

Трябва да погледнете приложението Swagger, както вече беше споменато от @zim2001. Той има компонент Swagger-ui, който е просто html и javascript приложение, което чете json данните, записани от бекенд приложението. Има адаптери за редица езици, включително php и java.

Ако използвате рамката Symfony2 за PHP, ето готов за използване пакет за автоматично генериране на документацията за услугата RESTful:

Едно нещо, което не ми харесва в такива генератори, е липсата на преводи, така че ако искате да предоставите документацията на вашия API, изложена през RESTful услуги на много езици - не можете.

person Nikola Petkanski    schedule 11.02.2013