Skip to content
Kitbay
Skill

openapi-spec-generation

MITUpdated on Nov 9, 202642,406GitHub stars

A skill from the documentation-generation plugin in wshobson's agents collection for writing, maintaining and checking OpenAPI 3.1 specifications for REST APIs.

Differs from the main skill, openapi-spec-generation (13% the same text). May be an adapted copy or an older version.

What the skill teaches

A skill from the documentation-generation plugin in wshobson's agents collection for writing, maintaining and checking OpenAPI 3.1 specifications for REST APIs. It outlines the main parts of a specification, from info and servers to paths, shared schemas and security schemes, and compares three ways of working: writing the specification before the code, generating it from existing code, or annotating code and generating from the annotations. A short list of practices asks for reusable components, realistic examples, every error code documented, versioning, explicit nullability, consistent naming and server variables instead of fixed URLs. Templates and worked examples sit in a separate reference file. It names no particular generator or validator.

Capabilities

  • Write an OpenAPI 3.1 specification
  • Choose design-first or code-first working
  • Define reusable schemas and security schemes