Dokumentacja REST API – Swagger

Dzisiaj chciałbym pokazać Swagger, doskonałe narzędzie służące do dokumentacji REST API.

Swagger, korzysta z plików JSON, którymi można opisać nasze API. W przypadku RESTful api m.in. możemy określić:

  1. Nazwę zasobu
  2. Typ zwracanych danych
  3. Opis obiektów
  4. Wersję API
  5. Zwracane kody statusu HTTP
  6. Parametry (np. query lub HTTP body)
  7. HTTP verbs (PUT, GET, POST etc)

Gotowy, przykładowy plik opisujący API możemy znaleźć tutaj:

http://petstore.swagger.io/v2/swagger.json

Oczywiście sam plik nie jest zbyt łatwy w odczycie dlatego zwykle korzysta się z Swagger-UI. Jest to prosta aplikacja internetowa, która wizualizuje wspomniany plik JSON. Dzięki niej możemy odczytywać dokumentację, jak i testować różne zapytania. Przykład:

http://petstore.swagger.io

Screenshot:

image

Pozostaje wyjaśnić jak stworzyć wspomniane pliki JSON. Ręczne edytowanie w pliku tekstowego jest dość mozolne.  Do dyspozycji mamy edytor online:

http://editor.swagger.io/#/

Screenshot:

image

Modyfikując plik, na bieżąco widać po prawej strony rezultat (podgląd).

Plik json opisujący API powinien być hostowany razem z usługą. Z kolei w przypadku Swagger-UI  jest to niekonieczne. Można np. mieć jedno repozytorium na całą firmę i tam trzymać swagger-ui, który wskazuje do poszczególnych usług. Inna możliwość to trzymanie swagger-ui razem z usługą i JSON.

Istnieje wiele frameworków, które integrują  Swagger z konkretną technologią np. ASP.NET MVC WebAPI. Wtedy framework wygeneruje JSON na podstawie np. komentarzy i analizy kodu. Bardzo wygodne i dzięki temu unikniemy rozbieżności między dokumentacją, a faktycznym stanem usługi.

Niestety nie znalazłem (na dziej dzisiejszy) dobrego narzędzia dla Nancy. Istnieje pewien projekt (wciąż w wersji PreAlph), ale nie jest zbyt stabilny:

https://github.com/khellang/Nancy.Swagger

Większość usług nad którymi pracuje jest napisana w Nancy, dlatego wciąż niestety edytuję plik ręcznie za pomocą przedstawionego wcześniej edytora online.

One thought on “Dokumentacja REST API – Swagger”

Leave a Reply

Your email address will not be published.