Tworzenie dokumentacji interfejsu API
Dokumentowanie interfejsu API repozytorium kodu źródłowego jest niezbędne do zapewnienia przejrzystości, ułatwień dostępu i łatwości korzystania z interfejsu API przez deweloperów. Kompleksowa dokumentacja służy jako przewodnik służący do zrozumienia funkcji, danych wejściowych, danych wyjściowych i użycia punktów końcowych interfejsu API. Podczas dokumentowania interfejsu API należy wybrać najbardziej odpowiedni format prezentacji (taki jak specyfikacja interfejsu OpenAPI lub Markdown), w tym przykłady i scenariusze użycia, zachować aktualność zmian kodu i poprosić użytkowników interfejsu API o ciągłą poprawę jakości.
Chociaż ogólne podejście do dokumentowania interfejsu API jest niezależne od platformy, istnieją pewne różnice w implementacji między usługą Azure DevOps i usługą GitHub.
Dokumentowanie interfejsu API w usłudze Azure DevOps
Aby dodać dokumentację interfejsu API do projektu usługi Azure DevOps w najbardziej wydajny sposób, rozważ użycie dedykowanego narzędzia lub platformy dokumentacji zintegrowanej z przepływem pracy programowania. Popularne opcje w tej kategorii obejmują struktury Swagger (OpenAPI), strategię interfejsu API i systemy dokumentacji oparte na języku Markdown, takie jak MkDocs lub Docusaurus. Ich możliwości integracji usługi Azure DevOps pomagają zautomatyzować proces dokumentacji generowania, zachowując synchronizację z bazą kodu. Większość narzędzi dokumentacji obsługuje również analizowanie komentarzy wbudowanych i uwzględnia je w dokumentacji generowanej automatycznie.
Należy opublikować dokumentację interfejsu API w centralnej lokalizacji dostępnej dla członków zespołu i uczestników projektu. Może to być dedykowana witryna internetowa dokumentacji, witryna typu wiki w usłudze Azure DevOps lub zewnętrzny portal dokumentacji.
Alternatywnie możesz 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 generować pliki specyfikacji OpenAPI.
Konfigurowanie zautomatyzowanych procesów w usłudze Azure Pipelines w celu automatycznego generowania dokumentacji interfejsu API za każdym razem, gdy nastąpi zmiana bazy kodu. Dzięki temu dokumentacja pozostaje aktualna i odzwierciedla najnowsze zmiany w interfejsach API.
Dokumentowanie interfejsu API w usłudze GitHub
W przypadku korzystania z usługi GitHub rozważ wygenerowanie dokumentacji interfejsu API, korzystając z 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 języka Markdown, aby uwzględnić jej szeroką obsługę i łatwość użycia. Zdefiniuj spójną strukturę 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, możesz użyć generatorów dokumentacji lub generatorów witryn statycznych, aby usprawnić proces generowania dokumentacji interfejsu API z plików Markdown. Popularne opcje to Jekyll, MkDocs, Docusaurus i Hugo. Skonfiguruj generator do analizowania plików Markdown i generowania statycznych stron HTML. Możesz dostosować układ, motyw i styl, aby dopasować znakowanie i preferencje projektu.
Aby opublikować zawartość HTML, skorzystaj z 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. Możesz również zaimplementować funkcję GitHub Actions, aby automatycznie kompilować i wdrażać dokumentację interfejsu API za każdym razem, gdy nastąpi zmiana plików dokumentacji lub bazy kodu.
Skonfiguruj funkcję GitHub Actions, aby automatycznie kompilować i wdrażać dokumentację interfejsu API za każdym razem, gdy nastąpi zmiana plików dokumentacji lub bazy kodu. Skonfiguruj przepływ pracy automatyzacji, aby wygenerować pliki dokumentacji HTML przy użyciu wybranego generatora dokumentacji i wdrożyć je w usłudze GitHub Pages.