422 lines
9.3 KiB
Markdown
422 lines
9.3 KiB
Markdown
# API Specification Standards
|
|
|
|
> OpenAPI vs OpenSpec guidance.
|
|
|
|
**Related:** [MODULAR_DOCUMENTATION.md](./MODULAR_DOCUMENTATION.md) | [DOCUMENTATION_UPDATES.md](../workflows/DOCUMENTATION_UPDATES.md)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document provides guidance on choosing between OpenAPI and OpenSpec for API documentation, including when to use each format, templates, and validation tools.
|
|
|
|
---
|
|
|
|
## OpenAPI Overview and Use Cases
|
|
|
|
### What is OpenAPI?
|
|
|
|
OpenAPI (formerly Swagger) is the industry-standard specification for describing RESTful APIs. It's widely supported by tools for documentation, code generation, and testing.
|
|
|
|
```yaml
|
|
# OpenAPI 3.0 basic structure
|
|
openapi: 3.0.0
|
|
info:
|
|
title: API Name
|
|
version: 1.0.0
|
|
paths:
|
|
/endpoint:
|
|
get:
|
|
summary: Description
|
|
responses:
|
|
'200':
|
|
description: Success
|
|
```
|
|
|
|
### OpenAPI Strengths
|
|
|
|
```
|
|
BEST FOR:
|
|
- REST APIs
|
|
- Public/external APIs
|
|
- APIs needing broad tooling support
|
|
- Code generation requirements
|
|
- Interactive documentation (Swagger UI)
|
|
- Contract-first development
|
|
```
|
|
|
|
### OpenAPI Tooling
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| Swagger UI | Interactive docs |
|
|
| Swagger Editor | Write and validate |
|
|
| OpenAPI Generator | Code generation |
|
|
| Postman | API testing |
|
|
| Stoplight | Design and docs |
|
|
|
|
---
|
|
|
|
## OpenSpec Overview and Use Cases
|
|
|
|
### What is OpenSpec?
|
|
|
|
OpenSpec is a specification format that may offer different capabilities or focus areas compared to OpenAPI. (Note: If referring to a specific OpenSpec project, details would go here.)
|
|
|
|
```yaml
|
|
# OpenSpec example structure (hypothetical)
|
|
openspec: 1.0.0
|
|
info:
|
|
title: API Name
|
|
version: 1.0.0
|
|
operations:
|
|
- name: getResource
|
|
path: /resource/{id}
|
|
method: GET
|
|
```
|
|
|
|
### OpenSpec Strengths
|
|
|
|
```
|
|
BEST FOR:
|
|
- Specific use cases where OpenSpec excels
|
|
- Projects already using OpenSpec
|
|
- Integration with OpenSpec-specific tools
|
|
- Non-REST API patterns
|
|
```
|
|
|
|
### OpenSpec Tooling
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| [OpenSpec tools] | [Purposes] |
|
|
|
|
---
|
|
|
|
## When to Use OpenAPI
|
|
|
|
### Use OpenAPI When:
|
|
|
|
```
|
|
✓ Building REST APIs
|
|
✓ Need Swagger UI documentation
|
|
✓ Require code generation
|
|
✓ Working with external partners
|
|
✓ Need broad ecosystem support
|
|
✓ Using API gateways (most support OpenAPI)
|
|
✓ Team is familiar with OpenAPI
|
|
```
|
|
|
|
### OpenAPI Version Guidance
|
|
|
|
| Version | Recommendation |
|
|
|---------|----------------|
|
|
| OpenAPI 3.0 | Recommended - Stable, widely supported |
|
|
| OpenAPI 3.1 | Use for JSON Schema alignment |
|
|
| Swagger 2.0 | Legacy - Migrate to 3.x |
|
|
|
|
---
|
|
|
|
## When to Use OpenSpec
|
|
|
|
### Use OpenSpec When:
|
|
|
|
```
|
|
✓ Project already uses OpenSpec
|
|
✓ Specific tooling requires OpenSpec
|
|
✓ Non-REST patterns better suited
|
|
✓ Team prefers OpenSpec workflow
|
|
✓ Integration with OpenSpec ecosystem
|
|
```
|
|
|
|
---
|
|
|
|
## Hybrid Approach Guidance
|
|
|
|
### When to Use Both
|
|
|
|
```
|
|
SCENARIOS FOR HYBRID:
|
|
|
|
1. Migration period
|
|
- Maintain both during transition
|
|
- Generate one from the other if possible
|
|
|
|
2. Different audiences
|
|
- OpenAPI for external partners
|
|
- OpenSpec for internal systems
|
|
|
|
3. Different API types
|
|
- OpenAPI for REST APIs
|
|
- OpenSpec for other patterns
|
|
```
|
|
|
|
### Keeping Specs in Sync
|
|
|
|
```
|
|
SYNC STRATEGIES:
|
|
|
|
1. Single source of truth
|
|
- Write in one format
|
|
- Generate the other automatically
|
|
|
|
2. Automated validation
|
|
- CI checks both specs match
|
|
- Alert on drift
|
|
|
|
3. Regular reconciliation
|
|
- Scheduled comparison
|
|
- Manual sync if needed
|
|
```
|
|
|
|
---
|
|
|
|
## Template Files
|
|
|
|
### OpenAPI 3.0 Template
|
|
|
|
```yaml
|
|
openapi: 3.0.0
|
|
info:
|
|
title: [API Name]
|
|
description: [Brief description]
|
|
version: 1.0.0
|
|
contact:
|
|
name: [Team Name]
|
|
|
|
servers:
|
|
- url: https://api.example.com/v1
|
|
description: Production
|
|
- url: https://staging-api.example.com/v1
|
|
description: Staging
|
|
|
|
paths:
|
|
/resource:
|
|
get:
|
|
summary: List resources
|
|
description: Returns a list of resources
|
|
operationId: listResources
|
|
tags:
|
|
- Resources
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 20
|
|
responses:
|
|
'200':
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Resource'
|
|
'401':
|
|
description: Unauthorized
|
|
'500':
|
|
description: Internal server error
|
|
|
|
post:
|
|
summary: Create resource
|
|
operationId: createResource
|
|
tags:
|
|
- Resources
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ResourceInput'
|
|
responses:
|
|
'201':
|
|
description: Created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Resource'
|
|
|
|
/resource/{id}:
|
|
get:
|
|
summary: Get resource by ID
|
|
operationId: getResource
|
|
tags:
|
|
- Resources
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Successful response
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Resource'
|
|
'404':
|
|
description: Not found
|
|
|
|
components:
|
|
schemas:
|
|
Resource:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
required:
|
|
- id
|
|
- name
|
|
|
|
ResourceInput:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
required:
|
|
- name
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
security:
|
|
- bearerAuth: []
|
|
```
|
|
|
|
### Minimal OpenAPI Template
|
|
|
|
```yaml
|
|
openapi: 3.0.0
|
|
info:
|
|
title: [API Name]
|
|
version: 1.0.0
|
|
paths:
|
|
/health:
|
|
get:
|
|
summary: Health check
|
|
responses:
|
|
'200':
|
|
description: OK
|
|
```
|
|
|
|
---
|
|
|
|
## Validation Tools and Commands
|
|
|
|
### OpenAPI Validation
|
|
|
|
```bash
|
|
# Using swagger-cli
|
|
npm install -g @apidevtools/swagger-cli
|
|
swagger-cli validate openapi.yaml
|
|
|
|
# Using spectral (with linting)
|
|
npm install -g @stoplight/spectral-cli
|
|
spectral lint openapi.yaml
|
|
|
|
# Using redocly
|
|
npm install -g @redocly/cli
|
|
redocly lint openapi.yaml
|
|
```
|
|
|
|
### Common Validation Errors
|
|
|
|
| Error | Cause | Fix |
|
|
|-------|-------|-----|
|
|
| Invalid reference | $ref points to non-existent schema | Check schema name |
|
|
| Missing required field | Required field not in properties | Add to properties |
|
|
| Invalid type | Wrong data type specified | Use valid OpenAPI types |
|
|
| Duplicate operationId | Same operationId used twice | Make unique |
|
|
|
|
### CI/CD Integration
|
|
|
|
```yaml
|
|
# GitHub Action for OpenAPI validation
|
|
- name: Validate OpenAPI
|
|
run: |
|
|
npm install -g @apidevtools/swagger-cli
|
|
swagger-cli validate ./api/openapi.yaml
|
|
```
|
|
|
|
---
|
|
|
|
## File Organization
|
|
|
|
### Recommended Structure
|
|
|
|
```
|
|
api/
|
|
├── openapi.yaml # Main spec file
|
|
├── schemas/ # Shared schemas
|
|
│ ├── user.yaml
|
|
│ └── error.yaml
|
|
├── paths/ # Path definitions
|
|
│ ├── users.yaml
|
|
│ └── resources.yaml
|
|
└── examples/ # Example requests/responses
|
|
└── user-example.json
|
|
```
|
|
|
|
### Splitting Large Specs
|
|
|
|
```yaml
|
|
# Main file references external files
|
|
openapi: 3.0.0
|
|
info:
|
|
title: Large API
|
|
paths:
|
|
/users:
|
|
$ref: './paths/users.yaml'
|
|
components:
|
|
schemas:
|
|
User:
|
|
$ref: './schemas/user.yaml'
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
```
|
|
+------------------------------------------------------------------+
|
|
| API SPECIFICATION QUICK REFERENCE |
|
|
+------------------------------------------------------------------+
|
|
| CHOOSE OPENAPI WHEN: |
|
|
| • Building REST APIs |
|
|
| • Need Swagger UI docs |
|
|
| • Need code generation |
|
|
| • Working with external partners |
|
|
+------------------------------------------------------------------+
|
|
| CHOOSE OPENSPEC WHEN: |
|
|
| • Project already uses it |
|
|
| • Specific tooling requires it |
|
|
+------------------------------------------------------------------+
|
|
| VALIDATE: |
|
|
| swagger-cli validate openapi.yaml |
|
|
| spectral lint openapi.yaml |
|
|
+------------------------------------------------------------------+
|
|
| FILE STRUCTURE: |
|
|
| api/ |
|
|
| ├── openapi.yaml (main) |
|
|
| ├── schemas/ (shared) |
|
|
| └── paths/ (endpoints) |
|
|
+------------------------------------------------------------------+
|
|
```
|
|
|
|
---
|
|
|
|
**Authored by:** TheArchitectit
|
|
**Document Owner:** Project Maintainers
|
|
**Last Updated:** 2026-01-14
|
|
**Line Count:** ~350
|