Dokumentace k vytvoření rozhraní API
Dokumentování rozhraní API úložiště zdrojového kódu je nezbytné pro zajištění přehlednosti, přístupnosti a snadného použití pro vývojáře, kteří rozhraní API udržují a využívají. Komplexní dokumentace slouží jako průvodce pro pochopení funkcí, vstupů, výstupů a využití koncových bodů rozhraní API. Při zdokumentování rozhraní API byste měli vybrat nejvhodnější formát prezentace (například specifikaci OpenAPI nebo Markdown), včetně příkladů a scénářů použití, udržovat ho v aktualizovaném stavu se změnami kódu a požádat uživatele rozhraní API o zpětnou vazbu, aby se neustále zlepšila jeho kvalita.
I když je obecný přístup k dokumentaci rozhraní API nezávislý na platformě, existují určité rozdíly v jeho implementaci mezi Azure DevOps a GitHubem.
Dokumentování rozhraní API v Azure DevOps
Pokud chcete do projektu Azure DevOps co nejefektivněji přidat dokumentaci k rozhraní API, měli byste zvážit použití vyhrazeného nástroje nebo platformy dokumentace, která se integruje s pracovním postupem vývoje. Mezi oblíbené volby v této kategorii patří Swagger (OpenAPI), podrobný plán rozhraní API a systémy dokumentace založené na Markdownu, jako jsou MkDocs nebo Docusaurus. Funkce integrace Azure DevOps pomáhají automatizovat proces dokumentace ke generování a udržovat je v synchronizaci se základem kódu. Většina nástrojů dokumentace podporuje také analýzu vložených komentářů a jejich zahrnutí do automaticky generované dokumentace.
Dokumentaci k rozhraní API byste měli publikovat do centrálního umístění přístupného členům týmu a zúčastněným stranám. Může to být vyhrazený web dokumentace, wikiweb v Rámci Azure DevOps nebo externí portál dokumentace.
Alternativně můžete pomocí poznámek ke kódu nebo dekorátorů přímo v kódu přidat metadata popisující jeho koncové body rozhraní API. Nástroje, jako je Swagger Codegen nebo Springfox, dokážou tyto poznámky zpracovat a vygenerovat soubory specifikace OpenAPI.
Nastavte automatizované procesy ve službě Azure Pipelines tak, aby automaticky generovaly dokumentaci k rozhraní API, kdykoli dojde ke změně základu kódu. Tím zajistíte, že vaše dokumentace zůstane aktuální a odráží nejnovější změny ve vašich rozhraních API.
Dokumentování rozhraní API na GitHubu
Při použití GitHubu zvažte generování dokumentace k rozhraní API s využitím nástrojů, které jsou součástí ekosystému GitHubu.
Začněte dokumentováním koncových bodů rozhraní API, operací, parametrů, odpovědí a dalších relevantních informací. Zvažte vytvoření této dokumentace ve formátu Markdown, která bude zohledňovat její širokou podporu a snadné použití. Definujte konzistentní strukturu jednotlivých dokumentů, rozdělte je do oddílů, které popisují ověřování, koncové body, parametry požadavků, příklady odpovědí atd.
Stejně jako u Azure DevOps můžete pomocí generátorů dokumentace nebo generátorů statických webů zjednodušit proces generování dokumentace rozhraní API ze souborů Markdownu. Mezi oblíbené volby patří Jekyll, MkDocs, Docusaurus a Hugo. Nakonfigurujte generátor tak, aby parsoval soubory Markdownu a vygeneroval statické stránky HTML. Rozložení, motiv a styly můžete přizpůsobit tak, aby odpovídalo brandingu a preferencím projektu.
Pokud chcete publikovat obsah HTML, využijte stránky GitHubu, které umožňují hostovat statické weby přímo z úložiště GitHub. Pro tento účel můžete vytvořit vyhrazenou větev a odeslat soubory HTML do této větve. GitHub Actions můžete také implementovat k automatickému sestavení a nasazení dokumentace k rozhraní API, kdykoli dojde ke změně souborů dokumentace nebo základu kódu.
Nastavte GitHub Actions tak, aby se automaticky sestavila a nasadila dokumentace k rozhraní API vždy, když dojde ke změně souborů dokumentace nebo základu kódu. Nakonfigurujte pracovní postup automatizace tak, aby pomocí zvoleného generátoru dokumentace vygeneroval soubory dokumentace HTML a nasadil je na GitHub Pages.