skills.rest
oliverconstance
oliverconstanceCOMMUNITY
Explore all skills by this author →
GitHub

openapi-spec-generator

Generates and validates OpenAPI 3.1 specifications with RFC 7807 error schemas for GCP Cloud Run services.

Updated Jul 24, 2026
Search Tags:#openapi#rest api#schema validation#google cloud run#api specification#yaml validation#rfc 7807
One-click install
npx skills add https://github.com/oliverconstance/webapp-scrum-team --skill openapi-spec-generator-oliverconstance
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openapi-spec-generator
Source: https://github.com/oliverconstance/webapp-scrum-team/tree/main/.agent/skills/openapi-spec-generator
Command: npx skills add https://github.com/oliverconstance/webapp-scrum-team --skill openapi-spec-generator-oliverconstance

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires ruamel.yaml, and includes scripts (resource) components.

What problem does it solve? Writing OpenAPI 3.1 specifications by hand is error-prone: teams often mix OpenAPI 3.0 syntax with 3.1, forget required metadata, or invent inconsistent error response formats. This Skill provides a standard operating procedure and a validation script to produce compliant, consistent API contracts for GCP-native microservices. ## Core Features & Use Cases - Step-by-Step Authoring Procedure: Guides you through declaring OpenAPI 3.1 metadata, server URLs for staging and production Cloud Run environments, paths, operations, and request/response schemas. - RFC 7807 Error Standardization: Enforces the standard problem details schema (type, title, status, detail, instance) for all 4xx and 5xx responses via a reusable YAML template. - Automated Validation: Ships a Python script that checks YAML syntax, OpenAPI 3.1 version compliance, required sections, and the presence of ProblemDetails schemas. - Use Case: Before opening a pull request for a new Cloud Run backend endpoint, run the validator to confirm your api-spec.yaml declares openapi 3.1.0, includes info and paths sections, and references the RFC 7807 ProblemDetails schema. ## Quick Start Ask the AI to generate an OpenAPI 3.1 specification for your Cloud Run service with RFC 7807 error responses, then validate it using the included validate_yaml.py script.

Frequently Asked Questions about openapi-spec-generator

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

FAQPage Schema
How do I validate an OpenAPI 3.1 YAML file in Python?▼

Run the included validate_yaml.py script with the --file flag pointing to your specification. It parses the YAML with ruamel.yaml, checks the openapi version starts with 3.1, verifies required info and paths sections, and warns if no RFC 7807 ProblemDetails schema exists.

How do I add RFC 7807 error responses to an OpenAPI spec?▼

Reference the ProblemDetails schema under components.schemas and use application/problem+json as the content type for 4xx and 5xx responses. The schema requires type, title, and status fields, with optional detail, instance, and errors arrays.

What is the difference between OpenAPI 3.0 and 3.1 for nullable fields?▼

OpenAPI 3.1 uses JSON Schema Draft 2020-12, so nullable: true from 3.0 is invalid. Instead, declare the type as a list such as [string, "null"] or use anyOf/oneOf constructs to express nullable fields.

Why does my OpenAPI validation fail with missing required property openapi?▼

This error occurs when the document header does not declare the specification version. Ensure the file starts with openapi: 3.1.0 rather than 3.0.0 or 3.0.3, since the validator rejects any version not starting with 3.1.

Can I use this validator for OpenAPI 3.0 specifications?▼

No, the validator explicitly rejects specifications whose openapi version does not start with 3.1. For OpenAPI 3.0.x documents, you would need a different validation tool or migrate the spec to 3.1 syntax first.

Related Skills

Explore More Software Engineering Skills→
rhuangabrielsantosrhuangabrielsantos

cy-create-techspec

Generate a _techspec.md file from a Product Requirements Document with interactive clarification.

Community
Advanced
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
azmankudusazmankudus

blueprint-webapi

Enforce API contracts using a single OpenAPI 3.1 master specification.

Community
Advanced
kumaran-iskumaran-is
34

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications for RESTful APIs.

Community
Advanced