OpenAPI Commands

Azu CLI provides comprehensive OpenAPI 3.1 support for both generating code from OpenAPI specifications and exporting OpenAPI specifications from your Crystal code.

Overview

The OpenAPI commands enable bidirectional integration between OpenAPI specifications and Azu applications:

Generate code from OpenAPI specifications
Export specifications from existing Azu code
Support OpenAPI 3.1 standard
Type-safe integration with Crystal

Available Commands

Command

Description

azu openapi:generate

Generate Crystal code from OpenAPI specification

azu openapi:export

Export OpenAPI specification from Crystal code

azu openapi:generate

Generates Crystal code from an OpenAPI 3.1 specification file, creating models, endpoints, requests, and responses.

Basic Usage

# Generate all code from OpenAPI spec
azu openapi:generate openapi.yaml

# Generate only models
azu openapi:generate openapi.yaml --models-only

# Generate only endpoints
azu openapi:generate openapi.yaml --endpoints-only

# Force overwrite existing files
azu openapi:generate openapi.yaml --force

Options

Option

Description

Default

--spec PATH

Path to OpenAPI specification file

Required

--force

Overwrite existing files without prompting

false

--models-only

Generate only models from schemas

false

--endpoints-only

Generate only endpoints from paths

false

Examples

Generate Complete API

# Generate all components from OpenAPI spec
azu openapi:generate api-spec.yaml

# Output:
# Parsing OpenAPI specification: api-spec.yaml
# Generated models: 5
# Generated endpoints: 12
# Generated requests: 8
# Generated responses: 12
# ✓ Code generation completed successfully

Generate Specific Components

# Generate only models
azu openapi:generate api-spec.yaml --models-only
# Generated models: 5
# ✓ Code generation completed successfully

# Generate only endpoints
azu openapi:generate api-spec.yaml --endpoints-only
# Generated endpoints: 12
# ✓ Code generation completed successfully

Force Overwrite

# Overwrite existing files
azu openapi:generate api-spec.yaml --force
# Overwriting existing files...
# ✓ Code generation completed successfully

Generated Code Structure

The generator creates the following files based on your OpenAPI specification:

src/
├── models/                    # Generated from schemas
│   ├── user.cr
│   ├── post.cr
│   └── comment.cr
├── endpoints/                 # Generated from paths
│   ├── users/
│   │   ├── index_endpoint.cr
│   │   ├── show_endpoint.cr
│   │   ├── create_endpoint.cr
│   │   ├── update_endpoint.cr
│   │   └── destroy_endpoint.cr
│   └── posts/
│       ├── index_endpoint.cr
│       └── show_endpoint.cr
├── requests/                  # Generated from request bodies
│   ├── users/
│   │   ├── create_request.cr
│   │   └── update_request.cr
│   └── posts/
│       ├── create_request.cr
│       └── update_request.cr
└── pages/                     # Generated from responses
    ├── users/
    │   ├── index_page.cr
    │   ├── show_page.cr
    │   └── create_page.cr
    └── posts/
        ├── index_page.cr
        └── show_page.cr

Generated Model Example

# src/models/user.cr
require "cql"

class User < CQL::Model
  table :users

  column :id, Int64
  column :name, String
  column :email, String
  column :created_at, Time
  column :updated_at, Time

  validates :name, presence: true
  validates :email, presence: true, format: /^[^@]+@[^@]+\.[^@]+$/
end

Generated Endpoint Example

# src/endpoints/users/index_endpoint.cr
class Users::IndexEndpoint < Azu::Endpoint
  def call
    users = User.all
    render_page(Users::IndexPage, users: users)
  end
end

Generated Request Example

# src/requests/users/create_request.cr
class Users::CreateRequest < Azu::Request
  field :name, String, required: true
  field :email, String, required: true, format: /^[^@]+@[^@]+\.[^@]+$/
end

Generated Response Example

# src/pages/users/show_page.cr
class Users::ShowPage < Azu::Page
  def initialize(@user : User)
  end

  def render
    template("users/show_page.jinja", {
      "user" => @user.to_h
    })
  end
end

Supported OpenAPI Features

Schemas (Component Models)

Basic types: string, integer, number, boolean
Complex types: object, array
Validation: required fields, format patterns, length constraints
Nested objects: automatically handled
Enums: converted to Crystal enums

Paths (Endpoints)

HTTP methods: GET, POST, PUT, PATCH, DELETE
Path parameters: automatically extracted
Query parameters: converted to request validation
Request bodies: generated as request classes
Responses: generated as page classes

Request/Response Bodies

JSON schemas: converted to Crystal structs
Validation rules: mapped to Azu validation
Nested objects: properly handled
Arrays: converted to Crystal arrays

OpenAPI Specification Example

# openapi.yaml
openapi: 3.1.0
info:
  title: Blog API
  version: 1.0.0
  description: A simple blog API

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - email
        - created_at

    CreateUserRequest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
      required:
        - name
        - email

azu openapi:export

Exports an OpenAPI 3.1 specification from your existing Azu application code.

Basic Usage

# Export to default file (openapi.yaml)
azu openapi:export

# Export to specific file
azu openapi:export --output api-spec.yaml

# Export as JSON
azu openapi:export --output api-spec.json --format json

# Export with custom project name and version
azu openapi:export --project "My API" --version "2.0.0"

Options

Option

Description

Default

--output PATH

Output file path

openapi.yaml

--format FORMAT

Output format (yaml, json)

yaml

--project NAME

Project name

Auto-detected from shard.yml

--version VERSION

API version

1.0.0

Examples

Export to YAML

# Export to default YAML file
azu openapi:export
# Building OpenAPI specification from code...
# ✓ OpenAPI specification exported to: openapi.yaml

Export to JSON

# Export to JSON file
azu openapi:export --output api-spec.json --format json
# Building OpenAPI specification from code...
# ✓ OpenAPI specification exported to: api-spec.json

Custom Project Information

# Export with custom project details
azu openapi:export --project "Blog API" --version "2.0.0" --output docs/api.yaml
# Building OpenAPI specification from code...
# ✓ OpenAPI specification exported to: docs/api.yaml

Code Analysis

The export command analyzes your Azu application and extracts:

Endpoints Analysis

HTTP methods from endpoint classes
Path patterns from route definitions
Request parameters from method signatures
Response types from return values

Models Analysis

Schema definitions from CQL models
Field types and constraints
Validation rules and formats
Relationships between models

Request/Response Analysis

Request classes and their fields
Response classes and their structure
Validation rules and constraints
Content types and formats

Generated OpenAPI Specification

The exported specification includes:

# Generated openapi.yaml
openapi: 3.1.0
info:
  title: My Application
  version: 1.0.0
  description: Generated from Azu application

servers:
  - url: http://localhost:4000
    description: Development server

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        email:
          type: string
          format: email
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - email
        - created_at
        - updated_at

    CreateUserRequest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
      required:
        - name
        - email

Workflow Integration

API-First Development

Design API using OpenAPI specification
Generate code from specification
Implement business logic in generated files
Export updated spec as you develop

# Start with OpenAPI spec
azu openapi:generate api-design.yaml

# Develop your application
# ... implement business logic ...

# Export updated specification
azu openapi:export --output updated-api.yaml

Code-First Development

Develop application with Azu endpoints and models
Export specification from existing code
Share specification with frontend/API consumers
Generate client code from specification

# Develop your application
# ... create endpoints and models ...

# Export OpenAPI specification
azu openapi:export

# Share with frontend team
# They can generate client code from openapi.yaml

Continuous Integration

# In CI pipeline
# Generate code from spec
azu openapi:generate api-spec.yaml

# Run tests
crystal spec

# Export updated spec
azu openapi:export --output generated-api.yaml

# Compare with original spec
diff api-spec.yaml generated-api.yaml

Best Practices

1. Specification Management

# Keep specifications in version control
git add openapi.yaml
git commit -m "Update API specification"

# Use meaningful file names
azu openapi:export --output "api-v1.2.0.yaml"

2. Code Generation

# Always review generated code
azu openapi:generate api-spec.yaml

# Customize generated files as needed
# ... edit generated files ...

# Regenerate when spec changes
azu openapi:generate api-spec.yaml --force

3. Validation

# Validate OpenAPI specification
# Use online validators or tools like swagger-codegen

# Test generated code
crystal spec

4. Documentation

# Export specification for documentation
azu openapi:export --output docs/api.yaml

# Generate API documentation
# Use tools like Swagger UI or Redoc

Troubleshooting

Common Issues

Invalid OpenAPI Specification

# Check specification syntax
cat openapi.yaml | head -20

# Validate with online tools
# https://editor.swagger.io/

Generation Failures

# Check for missing dependencies
crystal deps

# Verify file permissions
ls -la openapi.yaml

# Use verbose output for debugging
azu openapi:generate openapi.yaml --verbose

Export Issues

# Check if endpoints exist
ls -la src/endpoints/

# Verify model definitions
ls -la src/models/

# Check for compilation errors
crystal build src/main.cr

File Permission Issues

# Fix file permissions
chmod 644 openapi.yaml
chmod 755 src/

# Check directory permissions
ls -la

Memory Issues

# For large specifications
# Process in smaller chunks
azu openapi:generate openapi.yaml --models-only
azu openapi:generate openapi.yaml --endpoints-only

Integration Examples

Frontend Integration

# Export API specification
azu openapi:export --output frontend/api-spec.json --format json

# Frontend team can generate TypeScript client
# npx @openapitools/openapi-generator-cli generate -i api-spec.json -g typescript-axios -o src/api

API Documentation

# Export for documentation
azu openapi:export --output docs/api.yaml

# Generate Swagger UI
# Use tools like swagger-ui-dist or redoc-cli

Testing Integration

# Generate test data from spec
azu openapi:generate test-spec.yaml --models-only

# Use in test files
# require "./models/**"
# user = User.new(name: "Test", email: "test@example.com")

The OpenAPI commands provide powerful integration between OpenAPI specifications and Azu applications, enabling both API-first and code-first development workflows.

Next Steps:

Generate Command - Learn about code generation
Model Generator - Create database models
Endpoint Generator - Create HTTP endpoints
API Development Workflows - Learn API development patterns

PreviousDatabase Commands NextConfiguration Commands

Last updated 11 days ago

Good evening

hashtagOverview

hashtagAvailable Commands

hashtagazu openapi:generate

hashtagBasic Usage

hashtagOptions

hashtagExamples

hashtagGenerate Complete API

hashtagGenerate Specific Components

hashtagForce Overwrite

hashtagGenerated Code Structure

hashtagGenerated Model Example

hashtagGenerated Endpoint Example

hashtagGenerated Request Example

hashtagGenerated Response Example

hashtagSupported OpenAPI Features

hashtagSchemas (Component Models)

hashtagPaths (Endpoints)

hashtagRequest/Response Bodies

hashtagOpenAPI Specification Example

hashtagazu openapi:export

hashtagBasic Usage

hashtagOptions

hashtagExamples

hashtagExport to YAML

hashtagExport to JSON

hashtagCustom Project Information

hashtagCode Analysis

hashtagEndpoints Analysis

hashtagModels Analysis

hashtagRequest/Response Analysis

hashtagGenerated OpenAPI Specification

hashtagWorkflow Integration

hashtagAPI-First Development

hashtagCode-First Development

hashtagContinuous Integration

hashtagBest Practices

hashtag1. Specification Management

hashtag2. Code Generation

hashtag3. Validation

hashtag4. Documentation

hashtagTroubleshooting

hashtagCommon Issues

hashtagInvalid OpenAPI Specification

hashtagGeneration Failures

hashtagExport Issues

hashtagFile Permission Issues

hashtagMemory Issues

hashtagIntegration Examples

hashtagFrontend Integration

hashtagAPI Documentation

hashtagTesting Integration

Overview

Available Commands

azu openapi:generate

Basic Usage

Options

Examples

Generate Complete API

Generate Specific Components

Force Overwrite

Generated Code Structure

Generated Model Example

Generated Endpoint Example

Generated Request Example

Generated Response Example

Supported OpenAPI Features

Schemas (Component Models)

Paths (Endpoints)

Request/Response Bodies

OpenAPI Specification Example

azu openapi:export

Basic Usage

Options

Examples

Export to YAML

Export to JSON

Custom Project Information

Code Analysis

Endpoints Analysis

Models Analysis

Request/Response Analysis

Generated OpenAPI Specification

Workflow Integration

API-First Development

Code-First Development

Continuous Integration

Best Practices

1. Specification Management

2. Code Generation

3. Validation

4. Documentation

Troubleshooting

Common Issues

Invalid OpenAPI Specification

Generation Failures

Export Issues

File Permission Issues

Memory Issues

Integration Examples

Frontend Integration

API Documentation

Testing Integration