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ć:
- Nazwę zasobu
- Typ zwracanych danych
- Opis obiektów
- Wersję API
- Zwracane kody statusu HTTP
- Parametry (np. query lub HTTP body)
- 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:
Screenshot:
Pozostaje wyjaśnić jak stworzyć wspomniane pliki JSON. Ręczne edytowanie w pliku tekstowego jest dość mozolne. Do dyspozycji mamy edytor online:
Screenshot:
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.
Genialne -dzięki za podzielenie się wiedzą.