leo-claude-mktplace/plugins/saas-api-platform/skills/openapi-conventions.md

name, description

name	description
openapi-conventions	OpenAPI 3.x spec generation rules, path naming, schema definitions, response codes

OpenAPI Conventions

Purpose

Defines rules and patterns for generating and validating OpenAPI 3.x specifications. This skill ensures consistency between generated specs and industry best practices.

---

Specification Structure

An OpenAPI 3.0.3 document must include:

openapi: "3.0.3"
info:
  title: <project name>
  version: <project version>
  description: <project description>
servers:
  - url: <base url>
    description: <environment name>
paths:
  /<resource>: ...
components:
  schemas: ...
  securitySchemes: ...
tags: ...

---

Path Naming Rules

Rule	Example	Anti-Pattern
Plural nouns for collections	/users	/user, /getUsers
Lowercase with hyphens	/order-items	/orderItems, /order_items
Resource ID in path	/users/{user_id}	/users?id=123
Nested resources max 2 levels	/users/{id}/orders	/users/{id}/orders/{oid}/items/{iid}
No verbs in paths	/users + POST	/createUser
Version prefix when configured	/v1/users	/api/v1/users (redundant)

---

Response Code Standards

Method	Success	Client Error	Server Error
GET (single)	200	404	500
GET (list)	200	400 (bad params)	500
POST	201	400, 409 (conflict), 422	500
PUT	200	400, 404, 422	500
PATCH	200	400, 404, 422	500
DELETE	204	404	500

All endpoints should also document 401 (unauthorized) and 403 (forbidden) when auth is required.

---

Schema Definition Rules

1. Naming: PascalCase for schema names (UserCreate, OrderResponse)
2. Reuse: Use $ref for shared schemas instead of duplication
3. Required fields: Explicitly list required fields; do not rely on defaults
4. Types: Use specific types (integer not number for IDs; string with format: date-time for timestamps)
5. Descriptions: Every property should have a description field
6. Examples: Include example values for key properties
7. Nullable: Use nullable: true explicitly when fields can be null

---

Pagination Schema

List endpoints must return a paginated wrapper:

PaginatedResponse:
  type: object
  properties:
    items:
      type: array
      items:
        $ref: '#/components/schemas/ResourceResponse'
    total:
      type: integer
      description: Total number of items
    page:
      type: integer
      description: Current page number
    page_size:
      type: integer
      description: Items per page
    pages:
      type: integer
      description: Total number of pages

---

Security Scheme Patterns

JWT Bearer:

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

API Key:

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key

Apply globally or per-operation using the security field.