What happens if my documentation is out of sync?

The skill detects the drift, identifies the specific endpoints missing from your documentation, pauses current work, and prompts the use of the documentation-audit skill to resolve the discrepancy.

Can I skip the documentation check for internal changes?

Yes, the skill is designed to be skipped when changes are purely internal, involve only test files, or are modifications to the documentation itself.

Does it validate the actual OpenAPI file structure?

Yes, it can use tools like @apidevtools/swagger-cli or yq to validate that the specification file is well-formed and contains required top-level fields like paths and info.

Which frameworks does this skill support?

It supports a wide range of popular frameworks including Express, Fastify, NestJS, FastAPI, Flask, and Go by monitoring specific file patterns for routes and controllers.

Where does the skill look for API documentation files?

It automatically searches common project locations for files like openapi.yaml, openapi.json, swagger.yaml, and specialized folders like /docs or /api.

API Documentation Sync & Enforcement

Name: API Documentation Sync & Enforcement
Author: troykelly

bytroykelly

•

API開発

Ensures Swagger and OpenAPI documentation remains perfectly synchronized with your code changes automatically.

概要

This skill treats API documentation as a first-class artifact by monitoring for code changes in routes, controllers, and schemas across frameworks like Express, FastAPI, and NestJS. It automatically detects 'documentation drift' by comparing source code endpoints against OpenAPI or Swagger specifications. If a mismatch is found, the skill pauses work and triggers an audit to ensure that every API change is documented with required summaries, parameters, and response examples before code is shipped.

主な機能

Seamless integration with documentation-audit workflows
Enforcement of required documentation fields and response examples
Automatic drift detection between source code and OpenAPI/Swagger specs
5 GitHub stars
Automated validation using Swagger-CLI and schema checkers
Support for multiple frameworks including NestJS, FastAPI, and Express

ユースケース

Enforcing documentation standards across large-scale backend repositories
Preventing the release of undocumented endpoints or breaking API changes
Maintaining live API documentation during rapid feature development

概要

主な機能

Seamless integration with documentation-audit workflows
Enforcement of required documentation fields and response examples
Automatic drift detection between source code and OpenAPI/Swagger specs
5 GitHub stars
Automated validation using Swagger-CLI and schema checkers
Support for multiple frameworks including NestJS, FastAPI, and Express

ユースケース

Enforcing documentation standards across large-scale backend repositories
Preventing the release of undocumented endpoints or breaking API changes
Maintaining live API documentation during rapid feature development