openapi-authoring

OpenAPI Authoring Skill

When to Use This Skill

Use this skill when:

• Openapi Authoring tasks - Working on author and validate openapi 3.1 specifications for rest api design, following api-first and contract-first development practices
• Planning or design - Need guidance on Openapi Authoring approaches
• Best practices - Want to follow established patterns and standards

Overview

Author OpenAPI 3.1 specifications for REST API design using API-first methodology.

OpenAPI 3.1 Structure

Root Document

openapi: "3.1.0"

info:
  title: "{Service Name} API"
  version: "1.0.0"
  description: |
    {Service description and purpose}
  contact:
    name: "{Team Name}"
    email: "{team@company.com}"
  license:
    name: "MIT"
    identifier: "MIT"

servers:
  - url: "https://api.example.com/v1"
    description: "Production"
  - url: "https://api.staging.example.com/v1"
    description: "Staging"
  - url: "http://localhost:5000/v1"
    description: "Local development"

tags:
  - name: "{Resource}"
    description: "Operations for {resource} management"

paths:
  # Path definitions

components:
  # Reusable components

security:
  - bearerAuth: []

Path Operations

paths:
  /resources:
    get:
      operationId: "listResources"
      summary: "List all resources"
      description: "Retrieves a paginated list of resources"
      tags:
        - Resources
      parameters:
        - $ref: "#/components/parameters/PageNumber"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/SortBy"
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceListResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: "createResource"
      summary: "Create a new resource"
      description: "Creates a new resource with the provided data"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResourceRequest"
      responses:
        "201":
          description: "Resource created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
          headers:
            Location:
              description: "URL of the created resource"
              schema:
                type: string
                format: uri
        "400":
          $ref: "#/components/responses/BadRequest"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /resources/{resourceId}:
    parameters:
      - $ref: "#/components/parameters/ResourceId"

    get:
      operationId: "getResource"
      summary: "Get a resource by ID"
      description: "Retrieves a single resource by its unique identifier"
      tags:
        - Resources
      responses:
        "200":
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      operationId: "updateResource"
      summary: "Update a resource"
      description: "Replaces the entire resource with the provided data"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateResourceRequest"
      responses:
        "200":
          description: "Resource updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

    patch:
      operationId: "patchResource"
      summary: "Partially update a resource"
      description: "Updates specific fields of the resource"
      tags:
        - Resources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchResourceRequest"
      responses:
        "200":
          description: "Resource patched"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceResponse"
        "404":
          $ref: "#/components/responses/NotFound"

    delete:
      operationId: "deleteResource"
      summary: "Delete a resource"
      description: "Permanently removes a resource"
      tags:
        - Resources
      responses:
        "204":
          description: "Resource deleted"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"

Component Schemas

components:
  schemas:
    # Request schemas
    CreateResourceRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: "Resource name"
          example: "My Resource"
        type:
          $ref: "#/components/schemas/ResourceType"
        description:
          type: string
          maxLength: 500
          description: "Optional description"
        metadata:
          type: object
          additionalProperties: true
          description: "Custom metadata key-value pairs"

    UpdateResourceRequest:
      allOf:
        - $ref: "#/components/schemas/CreateResourceRequest"

    PatchResourceRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        description:
          type: string
          maxLength: 500
      minProperties: 1

    # Response schemas
    ResourceResponse:
      type: object
      required:
        - id
        - name
        - type
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier"
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          description: "Resource name"
        type:
          $ref: "#/components/schemas/ResourceType"
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: "Creation timestamp (ISO 8601)"
        updatedAt:
          type: string
          format: date-time
          description: "Last update timestamp (ISO 8601)"
        _links:
          $ref: "#/components/schemas/ResourceLinks"

    ResourceListResponse:
      type: object
      required:
        - data
        - pagination
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/ResourceResponse"
        pagination:
          $ref: "#/components/schemas/Pagination"
        _links:
          $ref: "#/components/schemas/PaginationLinks"

    # Enums
    ResourceType:
      type: string
      enum:
        - standard
        - premium
        - enterprise
      description: "Type of resource"

    # Common schemas
    Pagination:
      type: object
      required:
        - page
        - pageSize
        - totalItems
        - totalPages
      properties:
        page:
          type: integer
          minimum: 1
          description: "Current page number"
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          description: "Items per page"
        totalItems:
          type: integer
          minimum: 0
          description: "Total number of items"
        totalPages:
          type: integer
          minimum: 0
          description: "Total number of pages"

    ResourceLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        collection:
          type: string
          format: uri

    PaginationLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        first:
          type: string
          format: uri
        prev:
          type: string
          format: uri
        next:
          type: string
          format: uri
        last:
          type: string
          format: uri

    # Error schemas
    ErrorResponse:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: "URI reference identifying the problem type"
        title:
          type: string
          description: "Short, human-readable summary"
        status:
          type: integer
          description: "HTTP status code"
        detail:
          type: string
          description: "Human-readable explanation"
        instance:
          type: string
          format: uri
          description: "URI reference identifying the specific occurrence"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ValidationError"

    ValidationError:
      type: object
      required:
        - field
        - message
      properties:
        field:
          type: string
          description: "Field path (e.g., 'name' or 'address.city')"
        message:
          type: string
          description: "Validation error message"
        code:
          type: string
          description: "Error code for programmatic handling"

Parameters and Responses

components:
  parameters:
    ResourceId:
      name: resourceId
      in: path
      required: true
      description: "Resource unique identifier"
      schema:
        type: string
        format: uuid

    PageNumber:
      name: page
      in: query
      description: "Page number (1-indexed)"
      schema:
        type: integer
        minimum: 1
        default: 1

    PageSize:
      name: pageSize
      in: query
      description: "Number of items per page"
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortBy:
      name: sortBy
      in: query
      description: "Sort field and direction"
      schema:
        type: string
        pattern: "^[a-zA-Z]+:(asc|desc)$"
        example: "createdAt:desc"

    IfMatch:
      name: If-Match
      in: header
      description: "ETag for optimistic concurrency"
      schema:
        type: string

  responses:
    BadRequest:
      description: "Bad Request - Invalid input"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            type: "https://api.example.com/problems/bad-request"
            title: "Bad Request"
            status: 400
            detail: "The request body is malformed"

    Unauthorized:
      description: "Unauthorized - Authentication required"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    Forbidden:
      description: "Forbidden - Insufficient permissions"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    NotFound:
      description: "Not Found - Resource does not exist"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    Conflict:
      description: "Conflict - Resource state conflict"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    UnprocessableEntity:
      description: "Unprocessable Entity - Validation failed"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            type: "https://api.example.com/problems/validation-error"
            title: "Validation Error"
            status: 422
            detail: "One or more validation errors occurred"
            errors:
              - field: "name"
                message: "Name is required"
                code: "required"

    TooManyRequests:
      description: "Too Many Requests - Rate limit exceeded"
      headers:
        Retry-After:
          description: "Seconds until rate limit resets"
          schema:
            type: integer
        X-RateLimit-Limit:
          description: "Requests per window"
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: "Requests remaining"
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

Security Schemes

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT Bearer token authentication"

    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: "API key for service-to-service auth"

    oauth2:
      type: oauth2
      description: "OAuth 2.0 authentication"
      flows:
        authorizationCode:
          authorizationUrl: "https://auth.example.com/authorize"
          tokenUrl: "https://auth.example.com/token"
          refreshUrl: "https://auth.example.com/refresh"
          scopes:
            "read:resources": "Read access to resources"
            "write:resources": "Write access to resources"
            "admin:resources": "Administrative access"

C# Models for OpenAPI

using System.Text.Json.Serialization;

namespace SpecDrivenDevelopment.OpenApi;

/// <summary>
/// Represents an OpenAPI specification document
/// </summary>
public record OpenApiSpec
{
    public required string OpenApi { get; init; } = "3.1.0";
    public required OpenApiInfo Info { get; init; }
    public List<OpenApiServer> Servers { get; init; } = [];
    public Dictionary<string, OpenApiPathItem> Paths { get; init; } = [];
    public OpenApiComponents? Components { get; init; }
    public List<OpenApiSecurityRequirement> Security { get; init; } = [];
    public List<OpenApiTag> Tags { get; init; } = [];
}

public record OpenApiInfo
{
    public required string Title { get; init; }
    public required string Version { get; init; }
    public string? Description { get; init; }
    public OpenApiContact? Contact { get; init; }
    public OpenApiLicense? License { get; init; }
}

public record OpenApiContact
{
    public string? Name { get; init; }
    public string? Email { get; init; }
    public string? Url { get; init; }
}

public record OpenApiLicense
{
    public required string Name { get; init; }
    public string? Identifier { get; init; }
    public string? Url { get; init; }
}

public record OpenApiServer
{
    public required string Url { get; init; }
    public string? Description { get; init; }
    public Dictionary<string, OpenApiServerVariable>? Variables { get; init; }
}

public record OpenApiServerVariable
{
    public required string Default { get; init; }
    public List<string>? Enum { get; init; }
    public string? Description { get; init; }
}

public record OpenApiTag
{
    public required string Name { get; init; }
    public string? Description { get; init; }
}

public record OpenApiPathItem
{
    public string? Summary { get; init; }
    public string? Description { get; init; }
    public OpenApiOperation? Get { get; init; }
    public OpenApiOperation? Post { get; init; }
    public OpenApiOperation? Put { get; init; }
    public OpenApiOperation? Patch { get; init; }
    public OpenApiOperation? Delete { get; init; }
    public List<OpenApiParameter>? Parameters { get; init; }
}

public record OpenApiOperation
{
    public required string OperationId { get; init; }
    public string? Summary { get; init; }
    public string? Description { get; init; }
    public List<string>? Tags { get; init; }
    public List<OpenApiParameter>? Parameters { get; init; }
    public OpenApiRequestBody? RequestBody { get; init; }
    public required Dictionary<string, OpenApiResponse> Responses { get; init; }
    public List<OpenApiSecurityRequirement>? Security { get; init; }
    public bool Deprecated { get; init; }
}

public record OpenApiParameter
{
    public required string Name { get; init; }

    [JsonConverter(typeof(JsonStringEnumConverter))]
    public required ParameterLocation In { get; init; }

    public string? Description { get; init; }
    public bool Required { get; init; }
    public OpenApiSchema? Schema { get; init; }

    [JsonPropertyName("$ref")]
    public string? Ref { get; init; }
}

public enum ParameterLocation
{
    Query,
    Header,
    Path,
    Cookie
}

public record OpenApiRequestBody
{
    public string? Description { get; init; }
    public required Dictionary<string, OpenApiMediaType> Content { get; init; }
    public bool Required { get; init; }
}

public record OpenApiResponse
{
    public required string Description { get; init; }
    public Dictionary<string, OpenApiMediaType>? Content { get; init; }
    public Dictionary<string, OpenApiHeader>? Headers { get; init; }

    [JsonPropertyName("$ref")]
    public string? Ref { get; init; }
}

public record OpenApiMediaType
{
    public OpenApiSchema? Schema { get; init; }
    public object? Example { get; init; }
    public Dictionary<string, OpenApiExample>? Examples { get; init; }
}

public record OpenApiExample
{
    public string? Summary { get; init; }
    public string? Description { get; init; }
    public object? Value { get; init; }
}

public record OpenApiHeader
{
    public string? Description { get; init; }
    public OpenApiSchema? Schema { get; init; }
}

public record OpenApiSchema
{
    public string? Type { get; init; }
    public string? Format { get; init; }
    public string? Description { get; init; }
    public List<string>? Enum { get; init; }
    public object? Default { get; init; }
    public object? Example { get; init; }
    public List<string>? Required { get; init; }
    public Dictionary<string, OpenApiSchema>? Properties { get; init; }
    public OpenApiSchema? Items { get; init; }
    public bool? Nullable { get; init; }
    public int? MinLength { get; init; }
    public int? MaxLength { get; init; }
    public int? Minimum { get; init; }
    public int? Maximum { get; init; }
    public string? Pattern { get; init; }
    public List<OpenApiSchema>? AllOf { get; init; }
    public List<OpenApiSchema>? OneOf { get; init; }
    public List<OpenApiSchema>? AnyOf { get; init; }
    public bool? AdditionalProperties { get; init; }

    [JsonPropertyName("$ref")]
    public string? Ref { get; init; }
}

public record OpenApiComponents
{
    public Dictionary<string, OpenApiSchema>? Schemas { get; init; }
    public Dictionary<string, OpenApiParameter>? Parameters { get; init; }
    public Dictionary<string, OpenApiResponse>? Responses { get; init; }
    public Dictionary<string, OpenApiSecurityScheme>? SecuritySchemes { get; init; }
}

public record OpenApiSecurityScheme
{
    public required string Type { get; init; }
    public string? Scheme { get; init; }
    public string? BearerFormat { get; init; }
    public string? Description { get; init; }
    public string? Name { get; init; }
    public string? In { get; init; }
    public OpenApiOAuthFlows? Flows { get; init; }
}

public record OpenApiOAuthFlows
{
    public OpenApiOAuthFlow? AuthorizationCode { get; init; }
    public OpenApiOAuthFlow? ClientCredentials { get; init; }
}

public record OpenApiOAuthFlow
{
    public required string AuthorizationUrl { get; init; }
    public required string TokenUrl { get; init; }
    public string? RefreshUrl { get; init; }
    public required Dictionary<string, string> Scopes { get; init; }
}

public record OpenApiSecurityRequirement : Dictionary<string, List<string>>;

OpenAPI Design Patterns

Versioning Strategy

versioning_strategies:
  url_path:
    description: "Version in URL path"
    example: "/v1/resources"
    pros:
      - "Explicit and visible"
      - "Easy to route"
      - "Cache-friendly"
    cons:
      - "URL changes on major version"

  header:
    description: "Version in custom header"
    example: "X-API-Version: 2023-01-15"
    pros:
      - "Clean URLs"
      - "Fine-grained control"
    cons:
      - "Less discoverable"
      - "Harder to test in browser"

  query_parameter:
    description: "Version as query parameter"
    example: "/resources?version=2"
    pros:
      - "Easy to specify"
      - "Fallback to default"
    cons:
      - "Cache complications"
      - "Less clean"

  recommended: "url_path"
  rationale: "Most explicit, widely adopted, cache-friendly"

Pagination Patterns

pagination_patterns:
  offset_based:
    description: "Traditional page/pageSize pagination"
    parameters:
      - "page (1-indexed)"
      - "pageSize (default 20, max 100)"
    response:
      pagination:
        page: 2
        pageSize: 20
        totalItems: 150
        totalPages: 8
    pros:
      - "Simple to implement"
      - "Random access to pages"
    cons:
      - "Inconsistent with concurrent writes"
      - "Performance degrades at high offsets"

  cursor_based:
    description: "Cursor/continuation token pagination"
    parameters:
      - "cursor (opaque token)"
      - "limit (default 20, max 100)"
    response:
      pagination:
        nextCursor: "eyJpZCI6MTIzfQ=="
        hasMore: true
    pros:
      - "Consistent with concurrent writes"
      - "Better performance at scale"
    cons:
      - "No random access"
      - "Harder to implement"

  recommended: "cursor_based for large datasets, offset_based for small"

Error Handling (RFC 7807)

error_handling:
  standard: "RFC 7807 Problem Details"
  content_type: "application/problem+json"

  structure:
    type: "URI reference identifying problem type"
    title: "Short human-readable summary"
    status: "HTTP status code"
    detail: "Human-readable explanation specific to this occurrence"
    instance: "URI reference to specific occurrence"

  extensions:
    errors: "Array of field-level validation errors"
    traceId: "Correlation ID for debugging"

  example:
    type: "https://api.example.com/problems/validation-error"
    title: "Validation Error"
    status: 422
    detail: "The request contains invalid data"
    instance: "/resources/123"
    traceId: "abc-123-xyz"
    errors:
      - field: "email"
        message: "Invalid email format"
        code: "invalid_format"

Validation Checklist

openapi_validation_checklist:
  structure:
    - "Valid OpenAPI 3.1.0 syntax"
    - "All required fields present (openapi, info, paths)"
    - "No undefined $ref references"
    - "Consistent naming conventions"

  operations:
    - "Every operation has unique operationId"
    - "All operations have summary and description"
    - "All operations tagged appropriately"
    - "All path parameters defined"
    - "Response codes cover success and error cases"

  schemas:
    - "All schemas have descriptions"
    - "Required fields explicitly listed"
    - "Examples provided for complex types"
    - "Enums documented with descriptions"
    - "String formats specified (uuid, date-time, email, uri)"

  security:
    - "Security schemes defined"
    - "Operations specify security requirements"
    - "OAuth scopes documented"

  documentation:
    - "API description explains purpose"
    - "Contact information provided"
    - "Server URLs for all environments"
    - "Tags organized logically"

  best_practices:
    - "Use RFC 7807 for errors"
    - "Consistent pagination approach"
    - "HATEOAS links where appropriate"
    - "Idempotency keys for POST operations"
    - "ETag/If-Match for optimistic concurrency"

References

• references/openapi-patterns.md - Common OpenAPI design patterns
• references/api-guidelines.md - API design guidelines and standards

---

Last Updated: 2025-12-26