Zlepšete adopci API s OpenAPI specifikací
Délka:
8 min
Publikováno:
8. prosince 2022
V DX Heroes pracujeme na developer experience, jak pro naše vývojáře, tak pro vývojáře našich klientů. Čím víc firem staví na API, tím víc s API pracujeme i my. Navrhujeme jejich strukturu, vylepšujeme datové modely a ladíme dokumentaci. Po dost projektech se nám pořád vracel jeden vzorec. Firma se rozhodne zavést dokumentační standard, aby své API zpřehlednila nebo zlepšila jeho znovupoužitelnost, ale nedá do toho dost práce na to, aby to udělala pořádně. Výsledkem je dokument, který už neodpovídá skutečnému API, a developer experience se tím nezlepší, ale zhorší. Právě kvůli tomu jsem tento článek napsal. Shrnuje přínosy i úskalí toho, když používáte OpenAPI specifikaci nebo jiný formát, který API popisuje.
Co je OpenAPI specifikace?
OpenAPI specifikace je nejrozšířenější standard pro dokumentaci, vizualizaci a používání REST API. Technicky jde o YAML nebo JSON soubor s danou strukturou. Vznikla jako Swagger a v roce 2015 byla darována Linux Foundation. Dnes je to open-source projekt, který spravuje OpenAPI Initiative, konsorcium expertů, kteří vytvářejí, rozvíjejí a propagují formát popisu API nezávislý na dodavateli [1]. Postupem let začala spousta API nástrojů brát OpenAPI dokumenty jako vstup. Dnes můžete OpenAPI dokument poslat do nástrojů, které generují klientský nebo serverový kód, testují API, mockují ho a dokonce kontrolují bezpečnostní zranitelnosti. Celý seznam najdete na stránce OpenAPI [2]. S OpenAPI dokumentem se dá udělat hodně užitečných věcí, přesto spousta firem žádnou specifikaci nemá, nebo má takovou, která už jejich API neodpovídá.
Proč je OpenAPI důležité pro vás
Kvalitní OpenAPI specifikace usnadní práci lidem, kteří API staví, i lidem, kteří ho používají. Tady je jen malý zlomek toho, co vám přinese:
- API vývojáři a byznysoví lidé můžou společně iterovat na návrhu API, promyslet datové struktury a plánovat nové funkce.
- API vývojáři můžou OpenAPI spojit s nástroji a testovat i validovat reálnou implementaci.
- OpenAPI vám umožní postavit pro API developer portály, které pomáhají konzumentům.
- Konzumenti si přečtou OpenAPI dokument a rychle pochopí, jak API funguje, a provede je integrací.
- Z OpenAPI dokumentu můžete reálné API namockovat, takže se konzumenti soustředí na byznysovou logiku místo čekání na hotovou implementaci. To pomáhá větším partnerským firmám zkrátit cestu k MVP.
Asi největší přínos je generování kódu. Z OpenAPI dokumentu vygenerujete klientský kód skoro v jakémkoli jazyce a používání svého API tím výrazně zjednodušíte. Pokud je vaše API zároveň váš produkt, tohle vám může dát náskok před konkurencí. Vytvořit a udržovat kvalitní OpenAPI specifikaci ale není snadné.
Jak OpenAPI vytvořit a udržet při životě
Vytvořit a udržovat dobrý OpenAPI dokument stojí na disciplíně a na úzké spolupráci byznysu a vývoje. API a jeho OpenAPI dokument se obecně navrhují třemi způsoby: design-first, code-first a ruční psaní dokumentu až potom. Ruční přístup vynechám, protože ho za cestu k udržitelnému vývoji API nepovažuji.
Přístup design-first
U přístupu design-first vytvoříte nebo změníte OpenAPI dokument dřív, než napíšete jakýkoli kód API. Dokument je jediný zdroj pravdy a výsledné API se proti němu validuje. Když se vývojáři nebo byznys rozhodnou, že je potřeba API změnit, třeba kvůli nové funkci, nejdřív změnu navrhnou v OpenAPI dokumentu. Každý, koho se API týká, byznys i vývojář, má možnost změnu a její dopad promyslet. Navržené změny můžete probrat i s vybranými konzumenty, kterým důvěřujete, a dokonce jim vygenerovat mock API, aby si novou verzi vyzkoušeli. Teprve když je návrh schválený, mění se nebo implementuje kód API. Podle Postmanu [3] popularita tohoto přístupu stále roste.
Přístup code-first
U přístupu code-first už kód API existuje a vývojáři přidají nástroje, které OpenAPI specifikaci vygenerují z anotací v kódu. Tohle vyžaduje menší zapojení byznysu. Háček je v tom, že vývojáři občas zapomenou anotace aktualizovat, když mění kód. Tím vznikne nesoulad mezi OpenAPI specifikací a API, což může být vážný problém.
@ApiBearerAuth()
@ApiTags('cats')
@Controller('cats')
export class CatsController {
constructor(private readonly catsService: CatsService) {}
@Post()
@ApiOperation({ summary: 'Create cat' })
@ApiResponse({ status: 403, description: 'Forbidden.' })
async create(@Body() createCatDto: CreateCatDto): Promise<Cat> {
return this.catsService.create(createCatDto);
}
@Get(':id')
@ApiResponse({
status: 200,
description: 'The found record',
type: Cat,
})
findOne(@Param('id') id: string): Cat {
return this.catsService.findOne(+id);
}
}
Úskalí
Každý přístup má svá úskalí a vývojáři tak jako tak potřebují čas. Potřebují čas na to, aby API navrhli tak, že unese drobné změny, aniž by omylem vypustili breaking change. Potřebují čas na pořádné end-to-end testy, které ověří, že se API chová podle očekávání, a na automatizaci co největší části, aby měla lidská chyba menší prostor.
U design-first jsou úskalí hlavně v komunikaci mezi byznysem a vývojem. Byznysový tým se musí podílet na návrhu, což může být pomalé a o něco techničtější, než je zvyklý. Někdy byznys, nebo dokonce vývojáři, nevidí v OpenAPI dokumentu smysl a odmítnou se zapojit. Když k tomu dojde, vysvětlete přínosy pro každou konkrétní roli. Další překážkou jsou znalosti: vývojáři potřebují dobře rozumět návrhu API, aby s dokumentem pracovali, takže to obvykle není úkol pro juniory. A pak je tu udržování dokumentu a reálného API v souladu. Tady je to menší problém než u code-first, ale i tak se vyplatí pravidelně spouštět kontroly, které API proti dokumentu validují. Můžete je spouštět při commitech do hlavní větve v CI/CD pipeline.
U code-first směřují úskalí spíš k vývoji a to největší je udržet dokument a reálné API v souladu. Vývojové týmy potřebují pevné konvence pro změny API, pečlivé review každého PR, který sahá na API nebo specifikaci, a dobré pokrytí end-to-end testy, aby odhalily breaking changes i jakýkoli nesoulad. Méně technickým úskalím je opět komunikace mezi byznysem a vývojem. Když vázne, skončíte s API, které doopravdy nedělá to, co byznys potřebuje, nebo s vrstvami abstrakce, které zakrývají, k čemu API vlastně je.
Závěr
Kvalitní OpenAPI specifikace výrazně zlepší zkušenost API vývojářům i konzumentům, a když ji použijete dobře, dá vám náskok před konkurencí. Ten náskok něco stojí. Musíte udržet byznys a vývoj v rozhovoru a dát vývojářům dost času na technické procesy, které vyprodukují kvalitní API odpovídající dokumentu. Doufám, že vám tento článek dal vhled do úskalí dokumentace API a pomohl vám najít slabá místa, která vedou k problémům. Pokud se chystáte navrhovat API nebo se trápíte s jeho dokumentací, ozvěte se nám. Tohle je náš denní chleba.
Zdroje
Mohlo by vás také zajímat:
Chcete být o krok napřed?
Nenechte si utéct naše nejlepší postřehy. Žádný spam, jen praktické analýzy, pozvánky na exkluzivní eventy a shrnutí podcastů přímo do vaší schránky.