Design First a návrh REST API s aplikací Apidog

• Aplikace Apidog je zde (referal link)

Proč přecházím na Apidog

Apidog o sobě prohlašuje, že s ním nahradíte všechno od Postmanu, přes Stoplight až po Swagger UI a Mock. To je silné tvrzení, které se kupodivu ukázalo jako pravdivé.

Vezmu to velmi pragmaticky a jen vypíšu, co aplikace umí a co mě přesvědčilo na ji přejít ze Stoplight a zařadit ji do osnovy mého školení REST API Design.

Na úvod bych zmínil, že aplikace nabízí řadu funkcí zcela zdarma a už tato základní sada funkcí je mocnější než v případě Stoplight. Zdarma lze vytvořit 5 projektů, zveřejnit dokumentaci na subdoméně a připojit až 4 kolegy. Omezením může být jen jedna verze API na jeden projekt a pak omezení na 100 tisíc requestů na mock server (což je vlastně více než dost. Vyšší plány stojí 9/18/27 USD za uživatele na měsíc, což je pořád skvělá cena.

V druhé řadě má intuitivnější rozhraní a používá terminologii, která více odpovídá OAS. Nakonec samotné rozhraní je úžasné v tom, že například rozhraní pro odesílání požadavků vypadá jako Postman. Rozhraní pro návrh endpointů vypadá jako Stoplight. A princip organizací, týmů a projektů je zase něco, co známe třeba z Azure DevOps. Pro .NET vývojáře je UI zkrátka velmi intuitivní.

Přehled postřehů

Postřehy napíšu stručně, protože už připravuji video na YouTube, kde se rozpovídám více do detailů.

1. aplikaci lze poižívat online i v podobě desktop aplikace pro windows nebo macos
2. aplikace oproti stoplight za celé hodiny používání nevykázala jedinou chybu
3. základní funkce jsou: návrh endpointů, spouštění (ála Postman) a mockování
4. oproti Stoplight lze navrhnout endpoint na základě requestu
5. chybové stavy 4xx, 5xx se automaticky mohou připojovat k endpointům
6. lze si nastavit výchozí podobu 200 stavů
7. nejen, že lze přiřazovat k endpointům tagy (pro OAS), ale endpointy lze organizovat do složek (pro dokumentaci)
8. u každého endpointu (nebo složky) si lze nastavit viditelnost (Shared, Internal)
9. je možné připojit schéma k endpointu (třeba ProductResponse) a ten dekomponovat a upravit
10. všude jsou generátory kódu do všech možných jazyků
11. když přijde řeč na .NET a serializaci, oproti swaggeru je tu i podpora System.Text.Json
12. jednotlivé endpointy lze definovat s různými vlastními stavy: designing, release, deprecated
13. kromě proměnných jsou tu chytré placeholdery ve stylu Bogusu nebo FakeIt
14. místo testů (jako v Postmanu) se používají logičtější Pre Processors a Post Processors
15. místo kolekcí se vytváří nezávislé vícekrokové testovací scénáře
16. v rámci testovacích scénář je v beta programu i funkce performance (stress test)
17. mnohem lepší možnost při generování examples (náhodně, z jiných examples, dynamické)
18. je tu podpora lokálního i cloudového mockování, které si lze zvolit při testování rozhraní
19. u mockování si lze definovat mnohem snadněji scénáře a filtry (tzv. mock expectations)
20. krásná dokumentace an pure doméně, třeba zkuste courses.apidog.io
21. v dokumentaci si lze definovat vlastní meníčko a vlastní stránky v markdown
22. všechno frčí ve světlém i tmavém schématu dle vlastních preferencí
23. přímo z dokumentace si lze vygenerovat čisté DTOčka v C# s podporou System.Text.Json
24. lze si definovat export do více specifikačních formátů (verze OAS, YAML vs JSON)
25. v dokumentaci lze nastavit vlastní favicon, logo i barvičky
26. dají se připojit i Google Analytics, nastavit CORS nebo přidat pravidla pro redirecty mrtvých stránek
27. oproti Postmanu se rozlišuje kolekce a testovací scénář, což mi vždy extrémně vadilo

Pár screenshotů

Skvělá záložka pro nastavení viditelnosti endpointů:

Hlavní strana dokumentace s libovolným textem v markdown:

Snadné generování C# třídy na základě definice kontraktu v API:

Definice testovacího scénáře:

Níže můžete vidět výsledky performance testu daného testovacího scénáře vůči funkčnímu API v Azure.

Závěr

Revoluční. Po velmi dlouhé době jsem objevil nástroj, který mohu bez výhrad doporučit každému, do navrhuje REST API. Doposud jsem doporučoval kombinovat Stoplight, Postman, GitHub a vlastní generátor dokumentace jako například ReDoc. Nově stačí pouze tento nástroj. Umí absolutně všechno, co tým potřebuje pro návrh, testování, mockování API a to včetně přehledné dokumentace s funkčními generátory.