Jak dokumentujecie API?

[Wojtek Erbetowski]

Hej,

Zbieram właśnie informacje do nowego wykładu.

Jestem ciekaw jak dokumentujecie RESTowe API (i czy w ogóle to robicie)?

Czy trzymacie np dokumentację w docu czy korzystacie z narzedzia a'la Swagger, raml/apiary?

I czy z obecnej opcji jesteście zadowoleni?

Będę wdzięczny za podzielenie się wiedzą (jeśli ktoś się krępuje to na priv),

a w zamian chętnie podzielę się wnioskami (może w formie wykładu, może bloga).

Pozdrawiam

--

Cheers,

Wojtek Erbetowski

http://erbetowski.pl/

[Przemek Lewandowski]

Hej,

wierzymy w dokumentacje w kodzie i nigdzie dalej. Jeśli jest gdzieś indziej to staje się nieaktualna bardzo szybko. Dlatego w miarę możliwości trzymamy wszystko w kodzie np. w docstringach. Np. używając django rest frameworka mamy dokumentacje w markdown’ie, którą później można wygenerować lub udostępnić do zabawy wraz z web browseable API.

Pozdrawiam,

Przemek Lewandowski

@haxoza

--
Otrzymujesz tę wiadomość, bo subskrybujesz grupę „PyWaw” w Grupach dyskusyjnych Google.
Aby anulować subskrypcję tej grupy i przestać otrzymywać od niej wiadomości, wyślij e-maila na pywaw+un...@googlegroups.com.
Więcej opcji znajdziesz na https://groups.google.com/d/optout.

[Wojtek Erbetowski]

Dzięki wielkie!

A czy to browseable API to swagger?

[Piotr Szotkowski]

Wojtek Erbetowski:

> Jestem ciekaw jak dokumentujecie
> RESTowe API (i czy w ogóle to robicie)?

W świecie Ruby’ego/Rails popularne są Apiary i Apipie:

http://apiary.io
https://github.com/Apipie/apipie-rails

Jeśli masz siłę/czas dłużej rzucić okiem, to AmberBit skrobnął
notkę o budowaniu API, choć akurat o dokumentacji jest tam
skrawek (za to dokumentują starym dobrym Ruby’owym RDokiem):
http://www.amberbit.com/blog/2014/2/19/building-and-documenting-api-in-rails/

— Piotr Szotkowski
--
Dogmatyczne podejście kapłanów teologi linuksowego
zniewolenia zdejmuje z umysłów młodych programistów
obowiązek twórczego wątpienia w kanony uknute przez czas.
[Jarosław Protasiewicz, pl.comp.os.linux]

[Wojtek Erbetowski]

Dzięki za ten opis! Nie kojarzyłem projektu swagger-codegen

2014-08-30 12:23 GMT+02:00 Tomek Lipski <tomek....@gmail.com>:

Też używam Swaggera, a dokładnie - wystawiam API zgodne ze swagger-spec 1.2.

Serwis który buduję jest w Clojure, i mamy tam ogólną postać dokumentującą wejścia/wyjścia i model danych, z której:

 - na zewnątrz udostępniam specyfikację zgodną ze swagger-spec

 - podpinam swagger-ui do tego, 

 - generuję opis endpointów do standardowej dokumentacji (reszta jest w Markdown) 

 - tworzę reguły walidacyjne dla Prismatic Schema 

Oczywiście przeglądarka endpointów/dokumentacja to jedno, ponieważ jest jeszcze swagger-codegen (napisany w Scali), który umożliwia generowanie bibliotek klienckich do API dla popularnych technologii (Java, .NET, PHP, Python, Ruby, mobilne, ...). Dla NodeJS klient generuje się przy starcie serwera (ale jest też generator ponoć).

t

--
--
Wiadomość z grupy Warszawa Java User Group (Warszawa JUG).
Więcej informacji na stronie http://groups.google.com/group/warszawa-jug?hl=pl
Zachęcamy do odwiedzenia naszej strony domowej http://warszawa.jug.pl
Oferty pracy dozwolone zgodnie z zasadami na http://sites.google.com/site/warszawajug/oferty-pracy-na-grupie

---

Otrzymujesz tę wiadomość, bo subskrybujesz grupę „Warszawa Java User Group (Warszawa JUG)” w Grupach dyskusyjnych Google.
Aby anulować subskrypcję tej grupy i przestać otrzymywać od niej wiadomości, wyślij e-maila na warszawa-jug...@googlegroups.com.

Więcej opcji znajdziesz na https://groups.google.com/d/optout.