OpenAPI Spec Quality

The API reference pages are only as good as the OpenAPI specs behind them. The microservice-api-docs plugin scores each spec, blocks sensitive data, and fixes gaps in the service's source code — not in the generated spec.

Scoring

The quality skill reads the generated specs in docs/specs/, together with docs/intro.md and docs/environments.json. It never reads the service's source code and changes no files, so it works on any stack.

Metric	Weight
Operation descriptions	25%
Parameter descriptions	20%
Request examples	15%
Response examples	15%
`intro.md` quality	15%
Schema completeness	10%

A spec passes with a score of 60 or above and no blockers.

Sensitive Data

Sensitive data is a blocker — a spec that contains it fails, whatever its score. The skill checks for:

Specific partner IDs, especially negative (internal) ones
Internal hostnames, private IP addresses, and internal-only URLs
Credentials, secrets, and infrastructure details

Only public *.kaltura.ai and *.kaltura.com URLs can appear in published docs.

Fixing Low Scores

If the score is below the threshold, the plugin recommends the fix skill that matches the repository's technology:

Skill	Stack	What it changes
`fix-nestjs`	NestJS + `@nestjs/swagger`	Controllers and DTOs
`fix-fastapi`	FastAPI + Pydantic	Routes and models

The fix skills add missing operation summaries, property descriptions, and request and response examples. They only add what is missing and follow the repo's existing conventions, so running them again on a fixed repo changes nothing.

Fix the source, not the spec. The spec is regenerated from the code on every build, so edits made directly in the YAML are lost. The fix skills always edit the code the spec is generated from.

Running It Yourself

Run these from the root of the service repo:

/microservice-api-docs:quality        # score and list gaps
/microservice-api-docs:fix-nestjs     # NestJS: fix, regenerate, re-score
/microservice-api-docs:fix-fastapi    # FastAPI: fix, regenerate, re-score

Missing docs/intro.md or docs/environments.json? Run /microservice-api-docs:init to generate starter versions from the spec.

The same skills also run automatically on every staging deploy — see Staging & Production.

To change what the fix skills do or which data counts as sensitive, see Updating the Quality Skills.