Přejít k navigační liště

Zdroják » Různé » Jak na API dokumentaci

Jak na API dokumentaci

Články Různé

Pojďme se společně podívat na to, jak napsat API dokumentaci tak, aby byla srozumitelná jak lidem, tak strojům. Jak ji udělat udržitelnou, verzovanou a snadno dostupnou.

Nálepky:

Psaní dokumentace pro API je důležité, protože umožňuje vývojářům a dalším lidem, kteří s API pracují, snadné porozumění tomu, jak API funguje a jak se s ním pracuje. Zároveň je tato činnost často provázená značnou „bolestí”. Tato „bolest” pramení zejména z toho, že dokumentaci je potřeba udržovat, verzovat, doplňovat, upravovat nebo aktualizovat.

Dobrá API dokumentace by měla pomáhat vývojářům na obou stranách. Jak těm, kteří API využívají, tak těm, kteří se o API starají.

Co by měla API dokumentace obsahovat?

Dokumentace REST API by měla obsahovat informace o tom, jaké metody API podporuje, jaké parametry a hodnoty jsou k dispozici, jaké chyby a stavy mohou nastat a jak se s nimi zachází.

Dobrá dokumentace také obsahuje příklady volání v nějakém obvyklém jazyce, jako například PHP, Python nebo Javascript. Dobrá dokumentace API může pomoci snížit náklady na vývoj a zlepšit efektivitu práce s API.

Když si tohle vše dáte dohromady, automaticky vás napadne použít nějakou službu, která to vyřeší za vás. Ty samozřejmě existují, nejznámejší je asi Apiary nebo Postman.

Vždy je však důležité zvážit výhody a nevýhody používání externích služeb. Jakákoliv externí služba vás vždy připraví o část svobody a ztratíte kontrolu nad svým obsahem.

Jde to jinak?

OpenAPI Initiative byla založena v roce 2015. Je to komunita zabývající se vývojem a podporou OpenAPI specifikace, která je formátem pro popisování a dokumentování API. OpenAPI Initiative je podporována společnostmi, jako jsou Google, Microsoft, IBM, SAP, PayPal a další, a jejím cílem je poskytnout jednotný a snadno použitelný způsob pro popisování a dokumentování API.

Specifikace OpenAPI byla původně založena na specifikaci Swagger, kterou věnovala společnost SmartBear Software.

OpenAPI umožňuje používat několik různých formátů pro popisování a dokumentování API. Mezi nejčastěji používané patří JSON a YAML. Pojďme se společně podívat na příklad:

openapi: 3.0.0

info:
  title: "První API"
  description: |
    Tohle je úplný základ dokumentace

  termsOfService: https://server.com/terms-of-service
  version: 1.0.0
  contact:
    email: support@server.com

servers:
  - url: https://api.server.com/
    description: Popisek serveru


paths:
  /hello-world:
    get:
      operationId: Pozdrav
      description: Jen pozdravím a zase půjdu
      tags:
        - Hello
      responses:
        200:
          description: Úspěšný pozdrav
          content:
            text/plain:
              schema:
                type: string
                default: Ahoj lidi, zdravím

Ukázka dokumentuje API umístěné na adrese https://api.server.com/ s jedním endpointem /hello-world. Zavoláním adresy https://api.server.com/hello-world obdržíme textovou odpověď s obsahem Ahoj lidi, zdravím.

Není třeba zdůrazňovat, že takto vypadající dokumentaci můžete snadno verzovat například pomocí GITu, poslat kamarádovi nebo strojově zpracovávat.

OpenAPI a editory

Všechny oblíbené editory formátu YAML a JSON rozumí, takže napsat dokumentaci není problém. Pro psaní dokumentace můžete použít dokonce online editor od SmartBear Software.

Zkuste si tam vložit náš příklad, nebo si přes menu Edit > Load Petstore OAS 3.0 načíst Petstore dokumentaci.

Načtení příkladu Petstore v OpenAPI editoru

Osobně jsem si vystačil s vestavěnou podporou v PhpStorm. Pokud máte raději třeba Visual Studio Code, nejlépe fungoval plugin OpenAPI (Swagger) Editor.

Jak svoji dokumentaci k lidem?

Existuje několik způsobů, jak dostat vaši novou OpenAPI dokumentaci k lidem. Můžete jim dát možnost stáhnout zdrojový openapi.yaml soubor, nebo jim dokumentaci předgenerujete do čitelnější podoby nějakým generátorem.

Generátorů a různých nástrojů pro OpenAPI existuje celá řada. Nejsnažší je sáhnout po Swagger UI, který je součástí online editoru a generuje jednoduché, snadno čitelné HTML.

Výstup Swagger UI

Dalšími generátory jsou například ReDoc nebo DapperDox.

Znáte Docusaurus?

Docusaurus je oblíbený open source nástroj pro správu a vytváření dokumentace od vývojářů Facebooku. Docusaurus je navržen tak, aby byl snadno použitelný pro vývojáře, jako základní formát používá Markdown a dokáže své statické výstupy generovat například do GitHub Pages. Docusaurus obsahuje integrované funkce pro vyhledávání, lokalizaci či verzování dokumentace a možné jej snadno rozšířit o nové funkcionality pomocí pluginů.

Samozřejmě existuje také pluginy, které umí zpracovat OpenAPI. Zkoušel jsem jich několik, nejvíc se mi osvědčil PaloAltoNetworks/docusaurus-openapi-docs. Funguje jako pre-generator a na základě OpenAPI dokumentace vygeneruje MDX soubory, kterým Docusaurus rozumí.

Příklad Petstore vygenerovaný pomocí Docusauru s pluginem

Autoři se snaží o maximální vizuální kompatibilitu. Vaše API dokumentace tak nevypadá jako dolepený přívažek. Jediné, s čím jsem bojoval, bylo nastavení pluginu samotného. Nakonec jsem se dopracoval k této podobě:

// ...
plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'openapi',
        docsPluginId: 'classic',
        config: {
          'moje-api': {
            specPath: 'api/openapi.yaml',            
            outputDir: 'docs/api',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
            },
          },
        },
      },
    ],
],
// ...

Soubory mdx jsou generovány do složky docs/api, kde je najde Docusaurus a zpracuje je. Odkazy jsou seskupené do kategorii základě tagů, což usnadní orientaci – do vašeho package.json pak už stačí přidat jen tohle:

{
  //...
  "scripts": {
    "api": "docusaurus gen-api-docs all",
		"api:clean": "docusaurus clean-api-docs all",
		"api:regenerate": "yarn api.clean && yarn api"
  }
  // ...
}

Zdrojáky komplexnější příkladu najdete zde: https://github.com/testomato/help.testomato.com

Ještě jedna drobnost závěrem

OpenAPI je relativně ukecané, je tedy dobré dokumentaci rozdělit do více souborů a odkazovat se pomocí $ref. Vyplatilo se mi zejména oddělit responses (odpovědi), které mohou být velmi dlouhé, zejména pokud je odpověď struktorovaný JSON.

Jestliže, stejně jako já, nehodláte trávit hodiny přepisování JSON formátu do OpenAPI, zkuste mock-to-openapi. Je to malá knihovna, kterou jsem si napsal právě proto. Jakýkoliv vstupní JSON soubor:

{
  "title": "This is title",
  "author": "Roman Ožana",
  "content": "This is just an example",
  "date": "2020-05-12T23:50:21.817Z"
}

Převede na YAML odpovídající OpenAPI specifikaci:

type: object
properties:
  title:
    type: string
    example: This is title
  author:
    type: string
    example: Roman Ožana
  content:
    type: string
    example: This is just an example
  date:
    type: string
    format: date-time
    example: 2020-05-12T23:50:21.817Z

Komentáře

Subscribe
Upozornit na
guest
6 Komentářů
Nejstarší
Nejnovější Most Voted
Inline Feedbacks
View all comments
Lukáš Brzák

Psát dokumentaci ručně není pohodlné, doporučuji využít k tomu frameworky / tooling, který je spjatý s kódem či typy.

V TypeScriptu třeba Zod, který má knihovnu Zod-to-OpenApi. Píšeš kód a rovnou se z typů generuje schéma. Nechceš to udržovat ručně :-)

V PHP světě je třeba pro Symfony NelmioApiDocBundle nebo rovnou celá ApiPlatform, která je velmi mocná.

RIchard Kořínek

Pro API psané v Typescriptu je vynikající framework Nest (https://nestjs.com/). Umí používat typy a dále se jednotlivé RESTful routy popisují přímo pomocí anotací. Za sebe rozhodně doporučuju.

Jan

Doplním, že pro Python je tu skvělý nástroj FastAPI.

Pro API vytvořené pomocí FastAPI máte automaticky k dispozici interaktivní dokumentaci a OpenAPI schema.

OpenAPI schema je možné použít pro vygenerování API klienta (~ SDK), například v TypeScriptu ( https://fastapi.tiangolo.com/advanced/generate-clients/ ) nebo Pythonu ( https://github.com/openapi-generators/openapi-python-client ).

Víc na https://openapi.tools/#sdk.

Petr

Ano, pokud píšeš v jednom člověku server a zároveň i klienta, nebo to bude používat pár lidí v jedné firmě. Pokud probíhá integrace dvou firem a ty řešíš server část (API), těžko druhé straně řekneš: počkejte mi pár měsíců, musím to naprogramovat a pak vám teda vygeneruju tu dokumentaci. Nakonec jim slavnostně předáš dokumentaci a oni ti to hodí na hlavu, protože to pro ně bude nepoužitelné :)

Nehledě na to, jak autor článku správně píše hned v perexu: dokumentace by měla být srozumitelná lidem. Pokud budeš dokumentaci generovat z anotací a podobných nesmyslů, nic extra lidského z toho nevyleze. Ale větší problém je to co jsem psal v prvním odstavci, tedy když je nutnost bavit se předem nad tím, jak API bude vypadat, tedy jít metodou „API-first“.

Nejsi náhodou jeden z těch, co se vždy hlasitě ozvou, když musí pracovat s něčím co nemá dobrou dokumentaci? Ale pokud máš nějakou napsat, je to najednou nepohodlné co? :D

Náhodný kolem jdoucí

Mno, já myslel že soudružské firmě se dodá interfejs a pak se v klidu implementuje. Nebo jak se to dělá?

Petr

Mno, dodá se ji domluvený předpis API, který svým způsobem je „interfejsem“ a ke kterému dostala šanci se vyjádřit. Je jedno zda-li je to API Blueprint nebo OpenAPI Spec. Může ihned začít vyvíjet, jelikož má k dispozici nástroje, které ji vytvoří mock server a který si snadno mohou zaintegrovat do CI/CD přimo k aplikaci, kde se budou na API napojovat.

Enum a statická analýza kódu

Mám jednu univerzální radu pro začínající programátorty. V učení sice neexistují rychlé zkratky, ovšem tuhle radu můžete snadno začít používat a zrychlit tak tempo učení. Tou tajemnou ingrediencí je statická analýza kódu. Ukážeme si to na příkladu enum.