Co to znamená
Nic v docs/generated/openapi.json se nepíše ručně a nic v tom není napsáno jen pro OpenAPI. Každý tag je modul registru popsaný vlastními slovy modulu. Každý příklad na parametru dotazu nebo těle požadavku je jeden z případů měření schopnosti, jmenovitě: vstupy, které měření časují a které sada crate přehrává přes skutečný socket. Každá odpověď je stav, na který router umí u daného druhu schopnosti odpovědět: 200, 400 invalid_input, 404 not_found, 500 internal u každé operace, 422 refused jen u příkazu. Parametr dotazu se nikdy nedeklaruje jako nullable a nikdy nemá výchozí hodnotu null, protože query string je text a required: false už říká zbytek. info.summary, info.description, licence, kontakt a externalDocs pocházejí z about.rs a manifestu crate, tedy stejný text, jakým začínají instrukce MCP initialize a který nese HTTP index. Dokumentační web projektuje commitnutý dokument do svých dat, vykresluje /docs/api/ z této projekce a servíruje dokument surový na /openapi.json; externalDocs.url v dokumentu je tato trasa a kontroly webu odmítnou build, kde stránka, kopie nebo trasa chybí.
Princip
http/openapi.rs prochází registr: pro každou schopnost s HTTP expozicí se registru zeptá na poskytovatele případů té schopnosti, tutéž implementaci BenchmarkCases, kterou makro capability! vyžaduje od každého vstupního typu, a vyhodnotí ji proti indexu repozitáře, takže příklad pojmenovává objekt, který repozitář drží. Tagy jsou registry.modules() filtrované na moduly, které něco vystavují na drátě. Odpovědi se staví z jedné tabulky stavů, klíčované podle CapabilityKind. about.rs je jediný modul, který čtou OpenAPI info, mcp/protocol.rs a HTTP index. Request::bind obrací vazbu routeru, aby případy dosáhly na trasy tak, jak by je poslal klient, v tests/http_serve.rs i benches/routes.rs. scripts/generate-site-data promítá commitnutý dokument přes scripts/lib/openapi-site.jq do site/data/generated/openapi.json, odmítne operaci bez tagu, odpovědi nebo příkladu a zapíše odvozenou stránku; site/templates/api.html ji vykreslí; scripts/site-check vyžaduje každou operaci a tag na stránce a surový dokument na /openapi.json.
Jak to vidět
apps/majordomus-cli/target/debug/majordomus generate openapi --check # in sync
jq '.tags, .paths["/api/v1/object"].get.parameters[0].examples' docs/generated/openapi.json
jq '.paths["/api/v1/peers/announce"].post.responses | keys' docs/generated/openapi.json # 200, 400, 404, 422, 500, default
jq '.paths["/api/v1/object"].get.responses | keys' docs/generated/openapi.json # no 422: a query has nothing to refuse
cargo bench --manifest-path apps/majordomus-cli/Cargo.toml --bench routes # every route, every caseCo nepokrývá
Příklady odpovědí: vytvořit jeden by znamenalo spustit schopnost při sestavování dokumentu, a dokument je projekce, ne běh. Commitnutý dokument nese příklady indexu tohoto repozitáře, takže nový objekt, který se řadí první pod svým druhem, mění docs/generated/openapi.json a generate --check si žádá regeneraci, stejně jako u jakékoli jiné změny registru. Swagger UI na webu: web neposkytuje žádný skript třetí strany (scripts/site-check, pravidlo 8); běžící server poskytuje Swagger UI na /swagger nad týmž dokumentem, zatímco /docs je dokumentační web.
Proč existuje
Pravidlo provozovatele pro spustitelný soubor v Rustu: co lze odvodit z kódu, dat a anotací, se odvodí, zdokumentuje, otestuje, změří, automaticky zkontroluje a udržuje synchronizované; ručně psaný příklad driftuje, případ měření se přehrává. apps/majordomus-cli/tests/http_serve.rs přehraje případy každé cesty přes socket a ověří, že je dokument ukazuje; test/cases/92_openapi_reference.sh vygeneruje dokument v repozitáři, který zapsal init, zkontroluje štítky, příklady, stavy a text a ověří commitnuté kopie v tomto stromu proti registru, mezi sebou a proti webu.