---
name: "OpenAPI Spec Generation"
description: "Generates and maintains OpenAPI 3.1 specifications from code, with validation patterns and SDK generation support for consistent API contracts."
type: skill
roles: ["Engineering"]
activities: ["API Design", "Documentation"]
tags: ["API", "OpenAPI", "Documentation", "Contract"]
owner: "Integration Team"
version: "1.2.0"
sourceUrl: "https://github.com/qiscus/openapi-spec-generation"
compatibility: "Claude Code >= 1.0"
---

# OpenAPI Spec Generation

> Generates and maintains OpenAPI 3.1 specifications from code, with validation patterns and SDK generation support for consistent API contracts.

## Overview

OpenAPI Spec Generation automates the creation and maintenance of API contracts in OpenAPI 3.1 format. It reads existing code or design-first specs and produces comprehensive, validated documentation that teams can use to generate SDKs and verify endpoint compliance.

## Capabilities

| Capability | Description |
|---|---|
| Spec Generation | Creates OpenAPI 3.1 specs from route definitions and type annotations |
| Validation | Validates spec files against the OpenAPI standard |
| SDK Hints | Adds hints for common SDK generators (TypeScript, Python, Go) |
| Design-First | Supports writing specs first, then scaffolding matching code |
| Diff Detection | Identifies breaking changes between spec versions |

## Install Steps

### 1. Install via Claude Code

```bash
claude skill install openapi-spec-generation
```

### 2. Generate a spec from existing code

```
/openapi generate ./src/routes
```

### 3. Validate an existing spec file

```bash
/openapi validate openapi.yaml
```

Need help? Check the documentation or contact the Integration Team.