Springdoc yaml externalization

Skill kjuhwa/skills-hub/skills/backend/springdoc-yaml-externalization

Self-correcting knowledge corpus for Claude Code — 9 stable shape clusters, bias-correction pipeline baked into contribution flow. 47 papers, 45 techniques, 1.1k skills.

Install

npx -y skills add kjuhwa/skills-hub --skill springdoc-yaml-externalization

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Move long `@Operation description` and `@RequestBody examples` text out of Spring controllers into per-controller YAML files under `resources/api-docs/`, injected at runtime via a single `OperationCustomizer` bean. Swagger UI output unchanged.

SKILL.md

2.1 KB, as published. Nobody here has run it

springdoc OpenAPI YAML Externalization

Move long Swagger annotation text (description, request body examples, parameter docs) out of controllers into per-controller YAML under resources/api-docs/, injected at runtime via a single OperationCustomizer bean.

When to use

springdoc-openapi project where controllers are hard to read due to multi-line doc strings.
Want non-devs (TW / PO) to edit docs without touching Java.
No API surface change — only doc source relocated.

Steps

Add one SwaggerDocsConfig @Configuration exposing OperationCustomizer bean.
On startup, scan classpath:api-docs/*.yml and cache {controllerSimpleName → {methodName → docs}}.
In the customizer: look up by handlerMethod.getBeanType().getSimpleName() + handlerMethod.getMethod().getName() and inject description, requestBody.description, requestBody.examples, and parameters.<name>.description.
Create resources/api-docs/<ControllerName>.yml. Top-level keys are Java method names.
Strip description = """...""" and @io.swagger.v3.oas.annotations.parameters.RequestBody(...) from controllers. Keep summary inline for IDE help.
Parse example value: as JSON via Jackson; fall back to raw string on parse failure.

Gotchas

Spring's @RequestBody stays; only Swagger's @io.swagger.v3.oas.annotations.parameters.RequestBody goes.
Filename must exactly match controller SimpleName.
Load docsCache once at bean init — customizer runs per operation.

Complementary to swagger-ai-optimization (content quality for AI agents) — this one addresses source location of doc text, orthogonal concern.