Jak na API dokumentaci

Celý článek

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.

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.

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í.

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