playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / generating-api-contracts

generating-api-contracts skill

/plugins/api-development/api-contract-generator/skills/generating-api-contracts

This skill helps generate API contracts and OpenAPI specifications from code or design documents to streamline documentation.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill generating-api-contracts

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.4 KB
---
name: generating-api-contracts
description: |
  Generate API contracts and OpenAPI specifications from code or design documents.
  Use when documenting API contracts and specifications.
  Trigger with phrases like "generate API contract", "create OpenAPI spec", or "document API contract".
  
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:contract-*)
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Generating Api Contracts

## Overview


This skill provides automated assistance for api contract generator tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:contract-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill generates API contracts and OpenAPI specifications from code, design documents, or requirements. It automates resource model definition, endpoint scaffolding, schema documentation, and security requirements. The output includes route definitions, controllers, models, middleware and a complete OpenAPI 3.0 spec for developer and consumer use.

How this skill works

The skill inspects existing API specs, codebase directories, or supplied design documents to extract resources, methods, and data models. It maps endpoints to request/response schemas, infers authentication and error-handling patterns, and produces framework-ready boilerplate and an OpenAPI 3.0 specification. It can also scaffold tests, validation middleware, and configuration files to accelerate implementation.

When to use it

  • Document APIs before implementation to align teams and tools
  • Generate initial OpenAPI specs from legacy code or design docs
  • Scaffold endpoints and schemas for a new microservice
  • Create consistent API documentation for client SDK generation
  • Add or update authentication, validation, and error contracts

Best practices

  • Provide clear resource and data model definitions up front to reduce iteration
  • Include authentication and authorization requirements in the source docs
  • Use consistent naming and typing across models to ensure clean schema generation
  • Validate generated specs with OpenAPI linters and mock servers before implementation
  • Add integration tests and example requests to the generated output

Example use cases

  • Turn a design doc or Postman collection into an OpenAPI 3.0 spec for API-first development
  • Scan an existing codebase to produce up-to-date API documentation and endpoint stubs
  • Scaffold CRUD endpoints and database model bindings for a new service in Express, FastAPI, or Spring Boot
  • Generate contract-first tests and mock servers to enable parallel front-end and back-end work
  • Produce production-ready request validation and authentication middleware alongside the spec

FAQ

Can this skill generate specs for any framework?

It produces framework-agnostic OpenAPI specs and can scaffold boilerplate for common frameworks (Express, FastAPI, Spring Boot, Gin) but some manual adjustment may be required for project-specific patterns.

How do I ensure the generated OpenAPI is correct?

Supply clear models and examples, run OpenAPI linters, spin up a mock server, and add integration tests that exercise all endpoints and error flows.