SuperAPI AI Directory

openapi-specification

Coding & development

View repository

Updated 10-15 20:05

About this skill

OpenAPI Specification Skill

Overview

A skill specializing in the design and creation of API specifications compliant with the OpenAPI 3.x specification. Based on RESTful API design principles, it creates secure and highly maintainable API specifications. It comprehensively carries out endpoint design, schema definition, authentication/authorization settings, error handling, and documentation generation.

For detailed procedures and background, refer to the references/ directory.

Workflow

Phase 1: Requirements Definition

Purpose: Clarify the requirements for the API specification

Actions:

  1. references/basics.md to confirm the basic OpenAPI structure
  2. Define the number of endpoints, authentication method, and rate limits
  3. Check whether an existing API specification exists (determine whether to update or create new)

Phase 2: Specification Design

Purpose: Design and create the OpenAPI specification

Actions:

  1. agents/design-api.md to carry out the design
  2. assets/openapi-base-template.yaml as a base to create the specification
  3. references/schema-design-patterns.md for schema design
  4. references/security-schemes.md for security configuration

Task: agents/design-api.md refer to

Phase 3: Validation

Purpose: Validation and recording of the specification

Actions:

  1. agents/validate-spec.md to carry out validation
  2. scripts/validate-openapi.mjs for syntax checking
  3. Check security settings and best practices

Task: agents/validate-spec.md refer to

Task Specifications (Navigation)

Task Start Timing Input Output
design-api At the start of Phase 2 API requirements Specification draft
validate-spec At the start of Phase 3 Specification draft Validated specification

Detailed Specifications: For details of each Task, refer to the corresponding file in the agents/ directory

Best Practices

What to Do

  • When creating a new OpenAPI specification: openapi-base-template.yaml as a template and cover all sections: info, servers, paths, and components
  • When updating an existing OpenAPI specification: Clarify the differences in the specification before and after the change, and verify that there are no breaking changes
  • When designing endpoints or schemas: schema-design-patterns.md と openapi-structure.md to maintain consistency
  • When resolving OpenAPI syntax errors: validate-openapi.mjs to identify the specific error location before fixing it
  • When configuring security schemes: security-schemes.md best practices and apply appropriate authentication to all endpoints
  • Level-based Learning: Proceed in the order of Basics (Level 1) → Practical (Level 2) → Advanced (Level 3) → Expert (Level 4)
  • Version Management: Record the update history of the API specification in CHANGELOG.md and notify users of impacts

Things to Avoid

  • Avoid proceeding without checking anti-patterns and cautions
  • Do not add security scheme settings after the fact (incorporate them from the design stage)
  • Avoid inconsistent schema definitions across multiple endpoints
  • Do not skip defining error responses
  • required Do not make field specifications ambiguous
  • Do not hard-code security-related settings (make them switchable per environment)
  • Do not deploy to production while skipping validation of the OpenAPI specification

Resource references

references/ (detailed knowledge)

Resources Paths Purpose
Basic knowledge See references/basics.md OpenAPI basic structure
Structure guide See references/openapi-structure.md All section specifications
Schema Patterns See references/schema-design-patterns.md Schema design
Security See references/security-schemes.md Authentication and authorization settings

assets/ (Templates)

Resources Paths Purpose
Base Template assets/openapi-base-template.yaml Specification-based
Endpoints assets/endpoint-template.yaml Individual path definitions

Change history

Version Date Changes
1.2.0 2026-01-02 Added agents/, integrated Level structure
1.1.0 2025-12-31 Compliant with the 18-skills.md specification
1.0.0 2025-12-24 Initial implementation