Vlákno názorů k článku Mikroslužby založené na REST API od Jan - Popis specifikace API je nejvetsi slabina RESTu. Ve...
-
Popis specifikace API je nejvetsi slabina RESTu. Ve firme hledame nastroje a vlastne i format, ve kterem popsat stredne velke API. Kdyz pominu to, ze se stredne dlouhy yaml (dejme tomu 1500 radek) nekomu spatne cte (a nejen cloveku, ale i automatickym mergum pomoci gitu), pak je tu otazka, jakou specifikaci vlastne zvolit. OpenAPI 2 vs OpenAPI 3 vs RAML. Nastroje jsou taky bida, ale neco uz je. V holem editoru se to neda. A bacha na taby, myslim ze ani ty Pavle tam nemas validny yamly, proste pri copy pastovani se to obcas nekde rozsype.
-
L.Stříbrný podporovatel
No, formálně vzato možná ne, ale zato je to z hledisek, o kterých psal předřečník asi tak o dva až tři parníky lepší :)
-
Podle mě je obecně špatný přístup vytváření dokumentace nezávisle na kódu a programování podle specifikace. Naopak generování dokumentace z kódu není problém, všechny lepší frameworky to umožňují. Třeba django https://www.django-rest-framework.org/topics/documenting-your-api/
-
Filip JirsákStříbrný podporovatelProgramování podle specifikace budete vždy potřebovat – u těch REST služeb máte vždy minimálně dvě strany, vygenerovat dokumentaci z kódu můžete jen na jedné straně, na druhé pak musíte napsat kód podle té specifikace. Ideální je, když ta specifikace je ve strojově čitelném formátu, pak je možné z ní nechat vygenerovat struktury v příslušném programovacím jazyce. Já ty generátory kódu nerad používám pro produkční kód, ale třeba pro prototypování je to výborná věc.
Jinak je zajímavé, že ve světě XML je tohle vyřešené už spoustu let. Teď se to holt znova objevuje ve světě JSONu a vznikají OpenAPI (tam je alespoň proti WSDL něco trochu nového) nebo GraphQL (primitivní nápodoba XQuery).
-
Filip JirsákStříbrný podporovatel
Mohl byste alespoň nastínit, jak podle kódu REST serveru a testů (přičemž nic z toho ani nemusíte mít k dipozici) napíšete klienta té služby?
-
Filip JirsákStříbrný podporovatel
Fajn. Takže vaše předchozí dva komentáře můžeme škrtnout, protože neplatí, a zbývá nám tu ten problém uvedený v prvním komentáři vlákna, totiž že velkou slabinou současného RESTu je to, jak vytvářet specifikaci API. Protože vyjít z kódu je sice hezká věc, ale z toho dostanete menší a tu nejméně zajímavou část specifikace. Z toho dostanete jen názvy, struktury a jednoduché podmínky jako povinnost, maximální délku textu, rozsah hodnot apod. Pak to ale potřebujete obohatit o popis významu (což už je normální dokumentace, i když je obvykle součástí zdrojového kódu) a pak ještě o popis závislostí, postupů a předpokladů (které jsou sice v kódu zapsané, ale vyrobit z toho automaticky specifikaci nikdo neumí).
-
Filip JirsákStříbrný podporovatel
Nikoli, testy nepředstavují specifikaci. Test ověřuje některé vybrané případy, ověřuje správnost výsledků, ale neříká nic o tom, jak k tomu výsledku máte dojít ani proč to tak má být. Podle testu můžete napsat kód, který projde testem, ale to nijak nezaručuje, že je ten kód správně.
-
null null (neregistrovaný)
@Filip Jirsák
@gill
@Ondřej NěmečekTo vychází asi z nepochopení té obvyklé poznámky, že podle testů jde poznat, resp. z testů jde vyčíst jak se aplikace, resp. daný kód, chová nebo má chovat a že je to svým způsobem dokumentace kódu
To často je a lze to tak použít, ale není to hlavním účelem testů, není to ani nutná ani postačující podmínka a rozhodně to IMO nemá a nemůže nahradi specifikaci, protože právě ze specifikace se často právě vychází když se zachycují limity a stavy v testech.12. 7. 2019, 12:31 editováno autorem komentáře
-
Filip JirsákStříbrný podporovatel
@Ondrej Nemecek: Mohl byste být konkrétní a popsat, jak by vypadal test, který by byl zároveň specifikací? Třeba pro jednoduchost test pro funkci, které pro vstupní n vrací n. prvek posloupnosti 1, 2, 4, 8, 16…
-
Filip JirsákStříbrný podporovatel
@Tomáš Procházka: Ne, to není příklad testu, který by byl zároveň specifikací. To je jenom ukázka toho, že se příklady v dokumentaci automaticky testují. To je samozřejmě užitečná vlastnost, nefunkční příklady v dokumentaci jsou problém – ale je to něco úplně jiného, než o čem teoreticky píšou gilll nebo Ondrej Nemecek.
-
null null (neregistrovaný)
@Tomáš Procházka
Ve finále jste ten kód stejně musel popsat, jenom jste ty samotné údaje nezachytil do textu ale kódu, takže jste jenom k normální specifikaci přidal složitost ve formě nutnosti znalosti zvoleného jazyka a všech jeho možných sideefektů - tedy např. naprosto neuchopitelné pro běžnou tel. podporu atd.
13. 7. 2019, 00:01 editováno autorem komentáře
-
Ak by sa za špecifikáciu považovali ukážkové volania (aj s hlavičkami requestov a responsov), tak imho by mohla vyhovovať vhodne napísaná dokumentácia s rest-docs knižnicou (spring/java). Viď ukážka niekde ku koncu tuná https://g00glen00b.be/spring-rest-docs/
Osobne sa mi páči, že dokumentácia používa kusy skutočne vykonaných requestov z integračných testov a aserty z tých testov sú vlastne vygenerovaná dokumentácia. Takto sa dokumentácia (vpodstate špecifikácia) nerozíde s kódom tak jednoducho. -
Filip JirsákStříbrný podporovatel
Ukázková volání nejsou specifikace. Mohou být její součástí, jednoduché věci často člověk pochopí lépe z příkladu než ze specifikace, pro jednoduché a nedůležité věci často může ten příklad stačit. Ale rozhodně nestačí vždy. Jen pomocí příkladů se učí zvířata, lidské jazyky právě umožňují ta omezení příkladů překonat a komunikovat o složitějších věcech.
-
Ondra Satai NekolaZlatý podporovatel@gilll
To je hezka teorie, tenhle stav se mi libi... ale muze to fungovat jenom pro nektera (pracovne-organizacni) workflow.
-
Obecně špatné to možná je ale v konkrétních případech v tom problém nevidím.
Proč myslíte, že si vznikl connexion? Někdo měl právě opačný názor: https://github.com/zalando/connexion#why-connexion11. 7. 2019, 16:11 editováno autorem komentáře
-
Ten opačný názor byl princip "API First" viz také https://opensource.zalando.com/restful-api-guidelines/
-
Ten opačný názor byl princip "API First" viz také https://opensource.zalando.com/restful-api-guidelines/#api-first
-
No mám opačnou zkušenost, protože to vede k tomu, že se dokumentace nakonec neudělá, je zastaralá apod. A potom někdo (třeba i o dobré vůli) změní nějaký API call a je problém (vím vím, verzování API, ovšem v reálném světě je to chaos). Navíc když je popis v RAMLu/Swaggeru, tak se to už může implementovat v různých jazycích, opačně je to dost přes ruku.
-
Pavel TišnovskýZlatý podporovatelAhoj Honzo.
jj pro monolity s velkym mnozstvim koncovych bodu to muze byt zlo (vim o cem mluvim, nam par mikrosluzeb rozrostlo do monolitickych rozmeru :)
RAML uz bych asi nechal byt, IMHO je pro OpenAPI vice nastroju.
Ad validita: to je docela dobre mozne, zkusim to projet linterem a opravit (i kdyz v clanku to bude porad spatne, protoze redakcni system v kombinaci s prohlizecem taby a spol nedaji dobre nikdy:). Diky za upozorneni!
