api-documentation

Detect drift between API code changes and OpenAPI 3.x documentation.

10|Updated Jan 7, 2026

Search Tags:#documentation #api #openapi #validation #sync #swagger #code

Ready to run

npx skills add https://github.com/troykelly/codex-skills --skill api-documentation-troykelly

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-documentation
Source: https://github.com/troykelly/codex-skills/tree/main/skills/api-documentation
Command: npx skills add https://github.com/troykelly/codex-skills --skill api-documentation-troykelly

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill ensures that your API's code and its documentation (Swagger/OpenAPI) remain synchronized, preventing outdated documentation from causing integration issues or developer confusion.

Core Features & Use Cases

Automated Drift Detection: Automatically checks if API code changes (routes, schemas, controllers) have corresponding updates in the OpenAPI specification.
Enforced Documentation: Pauses development if drift is detected, requiring synchronization before proceeding.
Use Case: When a developer adds a new endpoint or modifies an existing one in the API code, this skill will immediately verify if the openapi.yaml file has been updated accordingly. If not, it flags the discrepancy and prompts for the documentation-audit skill to be run.

Quick Start

Use the api-documentation skill to verify that all API code changes are reflected in the openapi.yaml file.

Frequently Asked Questions about api-documentation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I keep my OpenAPI documentation in sync with API code?▼

To keep OpenAPI documentation in sync with API code, automated drift detection compares routes, endpoints, and schemas against the openapi.yaml file. This flags discrepancies whenever code changes lack corresponding documentation updates, preventing integration issues.

What happens when API code changes do not match the Swagger specification?▼

When API code changes do not match the Swagger specification, development pauses to enforce synchronization. The system detects drift in routes and schemas, requiring a documentation audit to update the OpenAPI 3.x file before proceeding with work.

Do I need OpenAPI 3.x standards to enforce API documentation synchronization?▼

Yes, you need OpenAPI 3.x standards to enforce API documentation synchronization. The validation process requires adherence to these specific standards to accurately detect drift in schemas, routes, and endpoints against the openapi.yaml file.

How does API documentation drift detection work for endpoints and schemas?▼

API documentation drift detection works by automatically checking if code changes in routes, schemas, and controllers have corresponding updates in the OpenAPI specification. It identifies mismatches between the code and openapi.yaml, pausing work to prompt a documentation audit.

When should I trigger a documentation audit for my API?▼

You should trigger a documentation audit for your API immediately after drift is detected between code changes and the OpenAPI specification. The enforcement mechanism pauses development work when routes, endpoints, or schemas lack corresponding openapi.yaml updates.