OpenAPI Spec Generator

Software development skill, available on Zeplik

OpenAPI Spec Generator is a ready-to-run software development skill on Zeplik. 1 specs: generate from pasted code, design-first contracts, validation, SDK generation. Ask in plain language and Zeplik applies the skill's method for you inside the conversation, on whichever AI model you prefer. It returns a structured document you can keep and reuse: Document artifact -- structured written deliverable with headed sections and a TL;DR (see artifact-templates/document.md).

The OpenAPI Spec Generator skill loads automatically when your request matches it, or you can invoke it directly by typing /openapi-spec-generation in any chat. It works with attachments, connectors, and any model that supports the task, so you get the same expert method every time without setting anything up.

What the OpenAPI Spec Generator skill can do

Try these prompts on Zeplik

Pick a prompt to open it in the Zeplik app. If you are not signed in yet, your prompt is waiting for you the moment you do.

How the OpenAPI Spec Generator skill works

/openapi-spec-generation

Create, maintain, and validate OpenAPI 3.1 specifications for RESTful APIs. The user pastes route handlers, controller code, or an existing spec; deliver complete, valid OpenAPI YAML (or JSON) as a chat artifact, with reusable components and documented error responses. For deciding resource modeling, verbs, pagination, and versioning strategy, use api-design-principles.

When to Use

  • Creating API documentation from scratch
  • Generating OpenAPI specs from existing code the user pastes
  • 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

ApproachDescriptionBest For
Design-FirstWrite spec before codeNew APIs, contracts
Code-FirstGenerate spec from codeExisting APIs
HybridAnnotate code, generate specEvolving APIs

Workflow

  1. Establish the source of truth: pasted code (code-first), a described contract (design-first), or an existing spec to extend or fix.
  2. Model schemas first in components/schemas with $ref reuse; then paths, parameters, and responses.
  3. Document every response the API can actually return, including 4xx/5xx error shapes.
  4. Define securitySchemes and apply them per-operation or globally.
  5. Deliver the full spec as one artifact; if it is large, deliver per-path fragments plus the components block with clear assembly instructions.
  6. Suggest validation (Spectral, Redocly CLI, swagger-cli) and downstream generation (openapi-generator, Redoc, Swagger UI) commands the user can run locally.

Best Practices

Do's

  • Use $ref -- reuse schemas, parameters, responses
  • Add examples -- real-world values help consumers
  • 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 (type arrays in 3.1)
  • Don't mix styles -- consistent naming throughout
  • Don't hardcode URLs -- use server variables

Templates and Detailed Worked Examples

The full template library (complete CRUD spec, auth schemes, pagination, webhooks) lives in references/details.md. Code-first generation from FastAPI/Express/Spring and tooling commands live in references/code-first-and-tooling.md. Read those files when you need the concrete templates.

Usage

/openapi-spec-generation $ARGUMENTS

How to use the OpenAPI Spec Generator skill

  1. Sign in to Zeplik

    Create a free Zeplik account or sign in. New accounts start with free credits, so you can try the OpenAPI Spec Generator skill right away.

  2. Describe your software development task

    Ask in plain language, or type /openapi-spec-generation to invoke the skill directly. Zeplik recognizes the OpenAPI Spec Generator skill and applies its method.

  3. Review and refine the result

    Zeplik returns a structured document you can edit, download, and reuse. Ask follow-ups to refine it.

Source and credit

Author
wshobson
License
MIT

Adapted from the open-source wshobson/agents project and tuned to run natively on Zeplik. View source on GitHub.

Frequently asked questions

What is the OpenAPI Spec Generator skill?
OpenAPI Spec Generator is a ready-to-run software development skill on Zeplik. 1 specs: generate from pasted code, design-first contracts, validation, SDK generation. Ask in plain language and Zeplik applies the skill's method for you inside the conversation, on whichever AI model you prefer. It returns a structured document you can keep and reuse: Document artifact -- structured written deliverable with headed sections and a TL;DR (see artifact-templates/document.md).
How do I use OpenAPI Spec Generator on Zeplik?
Sign in to Zeplik and ask in plain language, or type /openapi-spec-generation in any chat to invoke it directly. The skill applies its method and returns a result you can refine in the same conversation.
Which AI model does the OpenAPI Spec Generator skill use?
Any model you choose. Zeplik works across every model in one chat, so the OpenAPI Spec Generator skill runs on your preferred model for the task.
Where does the OpenAPI Spec Generator skill come from?
The OpenAPI Spec Generator skill is adapted from the open-source wshobson/agents project (MIT) and tuned to run natively on Zeplik. The original source is linked on this page.
How much does the OpenAPI Spec Generator skill cost?
Using the skill is free to start. You only spend Zeplik credits when the assistant runs, and new accounts begin with free credits.

Related software development skills

More on Zeplik

Try OpenAPI Spec Generator on Zeplik

Every model, one chat. Bring the OpenAPI Spec Generator skill into your next conversation and let the assistant do the work.

Browse all skills
OpenAPI Spec Generator - Software development skill for Zeplik AI | Zeplik Chat