56 results available

openapi-spec-generation

wshobson

·

Last changed

Hardened

This skill has been hardened by Chainguard

Last changed

This version passed the hardening gate. Hardening applied 3 targeted changes and preserved all other text. Classified findings before hardening: 6. Classified findings closed: 2. Classified findings remaining: 4. Unclassified scanner findings remaining: 0. Review findings closed: 2. Review findings remaining: 8.

Open before hardening

3

Medium

3

Low

Open after hardening

3

Medium

1

Low

File	Group	Subtype	Severity	Status
references/code-first-and-tooling.md	Sensitive Data & Secret Exposure	Data exfiltration	Medium	Open
references/details.md	Sensitive Data & Secret Exposure	Data exfiltration	Medium	Open
SKILL.md	Sensitive Data & Secret Exposure	Data exfiltration	Medium	Open
references/code-first-and-tooling.md	Malicious Code & Command Execution	—	Low	Closed
references/code-first-and-tooling.md	Tool & MCP Manipulation	MCP configuration abuse	Low	Open
references/code-first-and-tooling.md	Supply Chain & Install-Time Trust	Install-time download and execute	Low	Closed

6 findings

SKILL.md

OpenAPI Spec Generation

Comprehensive patterns for creating, maintaining, and validating OpenAPI 3.1 specifications for RESTful APIs.

When to Use This Skill

Creating API documentation from scratch
Generating OpenAPI specs from existing code
Designing API contracts (design-first approach)
Validating API implementations against specs
Generating client SDKs from specs
Setting up API documentation portals

Core Concepts

1. OpenAPI 3.1 Structure


openapi: 3.1.0
info:
  title: API Title
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /resources:
    get: ...
components:
  schemas: ...
  securitySchemes: ...

2. Design Approaches

Approach	Description	Best For
Design-First	Write spec before code	New APIs, contracts
Code-First	Generate spec from code	Existing APIs
Hybrid	Annotate code, generate spec	Evolving APIs

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Use $ref - Reuse schemas, parameters, responses
Add examples
Document errors - All possible error codes
Version your API - In URL or header
Use semantic versioning - For spec changes

Don'ts

Don't use generic descriptions - Be specific
Don't skip security - Define all schemes
Don't forget nullable - Be explicit about null
Don't mix styles - Consistent naming throughout
Don't hardcode URLs - Use server variables

Install

Install with chainctl


chainctl skill install public/wshobson/openapi-spec-generation:latest

Get started with chainctl

View source

Harden your own skills

Bring Chainguard's hardening pipeline to your first-party skills — custom rulesets, automated remediation, full audit trail.

Provenance

Upstream sourcehttps://github.com/wshobson/agents

Upstream commitbe57c0b2e3c05c528ca6132b87410b385718775f

OCI reference

skills.cgr.dev/public/github.com/wshobson/plugins/documentation-generation/skills/openapi-spec-generation:latest

License

MIT

Files

HARDENING.md

LICENSE

SKILL.md

references/code-first-and-tooling.md

references/details.md

The trusted source for open source

Talk to an expert

Privacy

Terms

© 2026 Chainguard, Inc. All Rights Reserved.
Chainguard® and the Chainguard logo are registered trademarks of Chainguard, Inc. in the United States and/or other countries.
The other respective trademarks mentioned on this page are owned by the respective companies and use of them does not imply any affiliation or endorsement.