api.define

Overview

api.define scaffolds OpenAPI and AsyncAPI specifications from enterprise-compliant templates, generating production-ready API contracts with best practices built-in.

Purpose

Quickly create API specifications that follow enterprise guidelines:

• •Generate Zalando-compliant OpenAPI 3.1 specs
• •Generate AsyncAPI 3.0 specs for event-driven APIs
• •Include proper error handling (RFC 7807 Problem JSON)
• •Use correct naming conventions (snake_case)
• •Include required metadata and security schemes

Usage

Basic Usage

python skills/api.define/api_define.py <service_name> [spec_type] [options]

Parameters

Examples

Example 1: Create Zalando-Compliant OpenAPI Spec

python skills/api.define/api_define.py user-service openapi --template=zalando

Output: specs/user-service.openapi.yaml

Generated spec includes:

• •✅ Required Zalando metadata (x-api-id, x-audience)
• •✅ CRUD operations for users resource
• •✅ RFC 7807 Problem JSON for errors
• •✅ snake_case property names
• •✅ X-Flow-ID headers for tracing
• •✅ Proper HTTP status codes
• •✅ JWT authentication scheme

Example 2: Create AsyncAPI Spec

python skills/api.define/api_define.py user-service asyncapi

Output: specs/user-service.asyncapi.yaml

Generated spec includes:

• •✅ Lifecycle events (created, updated, deleted)
• •✅ Kafka channel definitions
• •✅ Event payload schemas
• •✅ Publish/subscribe operations

Example 3: Custom Output Directory

python skills/api.define/api_define.py order-api openapi \
  --output-dir=api-specs \
  --version=2.0.0

Generated OpenAPI Structure

For a service named user-service, the generated OpenAPI spec includes:

Paths:

• •GET /users - List users with pagination
• •POST /users - Create new user
• •GET /users/{user_id} - Get user by ID
• •PUT /users/{user_id} - Update user
• •DELETE /users/{user_id} - Delete user

Schemas:

• •User - Main resource schema
• •UserCreate - Creation payload schema
• •UserUpdate - Update payload schema
• •Pagination - Pagination metadata
• •Problem - RFC 7807 error schema

Responses:

• •200 - Success (with X-Flow-ID header)
• •201 - Created (with Location and X-Flow-ID headers)
• •204 - No Content (for deletes)
• •400 - Bad Request (application/problem+json)
• •404 - Not Found (application/problem+json)
• •409 - Conflict (application/problem+json)
• •500 - Internal Error (application/problem+json)

Security:

• •Bearer token authentication (JWT)

Required Metadata:

• •x-api-id - Unique UUID
• •x-audience - Target audience (company-internal)
• •contact - Team contact information

Resource Name Extraction

The skill automatically extracts resource names from service names:

Naming Conventions

The skill automatically applies proper naming:

Integration with api.validate

The generated specs are designed to pass api.validate with zero errors:

# Generate spec
python skills/api.define/api_define.py user-service

# Validate (should pass)
python skills/api.validate/api_validate.py specs/user-service.openapi.yaml zalando

Use in Workflows

# workflows/api_first_development.yaml
steps:
  - skill: api.define
    args:
      - "user-service"
      - "openapi"
      - "--template=zalando"
    output: spec_path

  - skill: api.validate
    args:
      - "{spec_path}"
      - "zalando"
    required: true

Customization

After generation, customize the spec:

1. •Add properties to schemas:

User:
  properties:
    user_id: ...
    email:          # Add this
      type: string
      format: email

1. •Add operations:

/users/search:      # Add new endpoint
  post:
    summary: Search users

1. •Modify metadata:

info:
  contact:
    name: Your Team Name    # Update this
    email: team@company.com

Output

Success Response

{
  "status": "success",
  "data": {
    "spec_path": "specs/user-service.openapi.yaml",
    "spec_content": {...},
    "api_id": "d0184f38-b98d-11e7-9c56-68f728c1ba70",
    "template_used": "zalando",
    "service_name": "user-service"
  }
}

Dependencies

• •PyYAML: Required for YAML handling
  bash

  pip install pyyaml
  

Templates

See Also

• •api.validate - Validate generated specs
• •hook.define - Set up automatic validation
• •Betty Architecture - Five-layer model
• •API-Driven Development - Complete guide

Version

0.1.0 - Initial implementation with Zalando template support