Generate OpenAPI/Swagger specs from test automation code

OpenAPI / Swagger Specification Generator turns API descriptions, implementation code, or a partial specification into a complete API document. It supports OpenAPI 3.x and Swagger 2.0, and can produce YAML or JSON. The skill guides the user through choosing a version, output format, API purpose, endpoints, authentication, shared data models, and whether an existing specification should be extended. When source code is provided, it says to extract endpoints from the code rather than asking the user to repeat information already supplied.

The resulting document describes API metadata, servers, tags, paths, operations, parameters, responses, schemas, and security. OpenAPI 3.x places reusable schemas and security schemes under components; Swagger 2.0 uses definitions and its own host/basePath organization. For each operation, specify parameter location and required status, request body shape, response codes, and shared references. Preserve a supplied specification when extending it, validate serialization as YAML or JSON, and compare every inferred contract detail to implementation before publishing. The OpenAPI 3.x example uses info, servers, paths, and components; the Swagger 2.0 structure uses the corresponding version-specific organization. The workflow calls for a complete valid document and says not to leave placeholder comments such as TODO for missing schemas. It recommends reusable references for common responses and schemas where appropriate.

Use this skill when a team needs REST API documentation, an OpenAPI or Swagger file, YAML or JSON API schemas, or endpoint descriptions derived from code. It is useful when starting from a natural-language API outline, documenting existing routes, or extending a partial specification. It can also help reconcile version-specific differences such as servers versus host and components versus definitions.

The skill should not be used to invent endpoints, authentication, response behavior, or data models that the source does not establish. It is a specification drafting workflow, so the generated contract still needs comparison with the actual API implementation. If required details cannot be inferred, ask for them; infer details already present in user-provided code.

The source refers to API code from Express, FastAPI, Django URLs, and Spring controllers as material from which endpoints can be extracted. It covers OpenAPI 3.x and Swagger 2.0 structures and the YAML and JSON serialization formats. It does not require a particular generator library or hosted API service.

This skill is for API developers, platform teams, and technical writers creating or maintaining REST API contracts. It fits work where implementation routes or a clear API brief are available and where a complete, versioned specification is needed for documentation or integration. Reviewers should verify the generated paths, schemas, authentication, and responses against the real service before treating the file as authoritative.

openapi: "3.1.0"