Tworzenie dokumentacji interfejsu API

Tworzenie dokumentacji interfejsu API dla repozytorium kodu źródłowego jest bardzo ważne. Dobra dokumentacja ułatwia deweloperom zrozumienie, konserwację i łatwe korzystanie z interfejsu API. Kompletna dokumentacja wyjaśnia, jak działa interfejs API, jakie dane wejściowe potrzebuje, jakie dane wyjściowe daje i jak korzystać z punktów końcowych interfejsu API. Podczas tworzenia dokumentacji interfejsu API należy wybrać najlepszy format (taki jak specyfikacja interfejsu OpenAPI lub Markdown), uwzględnić przykłady i scenariusze użycia, aktualizować go podczas wprowadzania zmian w kodzie i prosić użytkowników interfejsu API o opinię, aby poprawić. Chociaż ogólne podejście do dokumentacji interfejsu API działa wszędzie, istnieją pewne różnice między usługą Azure DevOps i usługą GitHub.

Tworzenie dokumentacji interfejsu API w usłudze Azure DevOps

Aby wydajnie dodać dokumentację interfejsu API do projektu usługi Azure DevOps, należy użyć dedykowanego narzędzia dokumentacji, które współdziała z przepływem pracy programowania. Popularne opcje obejmują Swagger (OpenAPI), API Blueprint oraz systemy dokumentacji oparte na Markdown, takie jak MkDocs lub Docusaurus. Integracja usługi Azure DevOps pomaga zautomatyzować tworzenie dokumentacji i synchronizować ją z kodem. Większość narzędzi dokumentacji może również odczytywać komentarze wbudowane i dołączać je do automatycznie generowanej dokumentacji.

Należy opublikować dokumentację interfejsu API w centralnej lokalizacji, do której mogą uzyskiwać dostęp członkowie zespołu i uczestnicy projektu. Może to być dedykowana witryna internetowa dokumentacji, witryna typu wiki w usłudze Azure DevOps lub zewnętrzny portal dokumentacji.

Możesz również użyć adnotacji kodu lub dekoratorów bezpośrednio w kodzie, aby dodać metadane opisujące punkty końcowe interfejsu API. Narzędzia takie jak Swagger Codegen lub Springfox mogą przetwarzać te adnotacje i tworzyć pliki specyfikacji Interfejsu OpenAPI.

Konfigurowanie zautomatyzowanych procesów w usłudze Azure Pipelines w celu automatycznego tworzenia dokumentacji interfejsu API za każdym razem, gdy nastąpi zmiana kodu. Dzięki temu dokumentacja pozostaje aktualna i odzwierciedla najnowsze zmiany w interfejsach API.

Tworzenie dokumentacji interfejsu API w usłudze GitHub

W przypadku korzystania z usługi GitHub rozważ utworzenie dokumentacji interfejsu API przy użyciu narzędzi będących częścią ekosystemu usługi GitHub.

Zacznij od udokumentowania punktów końcowych interfejsu API, operacji, parametrów, odpowiedzi i innych odpowiednich informacji. Rozważ utworzenie tej dokumentacji w formacie markdown, ponieważ jest ona powszechnie obsługiwana i łatwa w użyciu. Zdefiniuj spójną strukturę dla poszczególnych dokumentów, dzieląc poszczególne sekcje na sekcje opisujące uwierzytelnianie, punkty końcowe, parametry żądania, przykłady odpowiedzi itp.

Podobnie jak w przypadku usługi Azure DevOps, generatory dokumentacji lub generatory witryn statycznych ułatwiają proces tworzenia dokumentacji interfejsu API z plików Markdown. Popularne opcje to Jekyll, MkDocs, Docusaurus i Hugo. Skonfiguruj generator, aby odczytywać pliki markdown i tworzyć statyczne strony HTML. Możesz dostosować układ, motyw i styl, aby dopasować identyfikację wizualną i preferencje projektu.

Aby opublikować zawartość HTML, użyj usługi GitHub Pages, która umożliwia hostowanie statycznych witryn internetowych bezpośrednio z repozytorium GitHub. W tym celu można utworzyć dedykowaną gałąź i wypchnąć pliki HTML do tej gałęzi. Za pomocą funkcji GitHub Actions można również automatycznie kompilować i wdrażać dokumentację interfejsu API za każdym razem, gdy nastąpi zmiana plików dokumentacji lub kodu.

Skonfiguruj funkcję GitHub Actions, aby automatycznie kompilować i wdrażać dokumentację interfejsu API przy każdej zmianie plików dokumentacji lub kodu. Skonfiguruj przepływ pracy automatyzacji, aby utworzyć pliki dokumentacji HTML przy użyciu wybranego generatora dokumentacji i wdrożyć je w usłudze GitHub Pages.