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.
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í.
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.
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ý pozdrave
content:
text/plain:
schema:
type: string
default: Ahoj lidi, zdravímUká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.
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.
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 oblíbenými generátory jsou ReDoc a DapperDox.
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
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. Vstupní JSON:
{
"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
