OpenAPI-Specific Options¶

When working with OpenAPI specifications, datamodel-code-generator provides several options to control how schemas, operations, and special properties are handled. This page explains when and how to use each option.

Quick Overview¶

--openapi-scopes¶

Controls which sections of the OpenAPI specification to generate models from.

Default behavior (schemas only)¶

datamodel-codegen --input openapi.yaml --output models.py

Generates models only from #/components/schemas.

Include parameters¶

datamodel-codegen --input openapi.yaml --output models.py \
  --openapi-scopes schemas parameters

Also generates models from #/components/parameters.

Include path-level definitions¶

datamodel-codegen --input openapi.yaml --output models.py \
  --openapi-scopes schemas parameters paths

Generates models from all sources, including inline path operation parameters.

When to use each scope¶

--include-path-parameters¶

Includes path parameters as fields in generated models.

OpenAPI Example¶

paths:
  /users/{user_id}/orders/{order_id}:
    get:
      operationId: getOrder
      parameters:
        - name: user_id
          in: path
          schema:
            type: string
        - name: order_id
          in: path
          schema:
            type: integer

Without --include-path-parameters¶

class GetOrderResponse(BaseModel):
    # Only response body fields
    items: list[Item]
    total: float

With --include-path-parameters¶

datamodel-codegen --input openapi.yaml --output models.py --include-path-parameters

class GetOrderResponse(BaseModel):
    user_id: str
    order_id: int
    items: list[Item]
    total: float

When to use¶

• Building request validation models that include URL parameters
• Creating unified request/response types for API clients
• Generating models for frameworks that expect all parameters in one object

--use-operation-id-as-name¶

Uses the operationId from OpenAPI operations to name generated models instead of deriving names from paths.

OpenAPI Example¶

paths:
  /users/{id}:
    get:
      operationId: getUserById
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }

Without --use-operation-id-as-name¶

class UsersIdGetResponse(BaseModel):  # Derived from path
    id: int
    name: str

With --use-operation-id-as-name¶

datamodel-codegen --input openapi.yaml --output models.py --use-operation-id-as-name

class GetUserByIdResponse(BaseModel):  # Uses operationId
    id: int
    name: str

When to use¶

• When operationId values are well-designed and descriptive
• For consistency with generated API clients (e.g., OpenAPI Generator)
• When path-derived names are too verbose or unclear

--read-only-write-only-model-type¶

Generates separate model variants for properties marked as readOnly or writeOnly in OpenAPI.

OpenAPI Example¶

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          readOnly: true        # Only in responses
        password:
          type: string
          writeOnly: true       # Only in requests
        name:
          type: string          # In both

Without --read-only-write-only-model-type¶

class User(BaseModel):
    id: Optional[int] = None      # Both included
    password: Optional[str] = None
    name: Optional[str] = None

With --read-only-write-only-model-type¶

datamodel-codegen --input openapi.yaml --output models.py \
  --read-only-write-only-model-type all

class User(BaseModel):
    """Base model with all fields."""
    id: Optional[int] = None
    password: Optional[str] = None
    name: Optional[str] = None

class UserRead(BaseModel):
    """For responses - excludes writeOnly fields."""
    id: Optional[int] = None
    name: Optional[str] = None

class UserWrite(BaseModel):
    """For requests - excludes readOnly fields."""
    password: Optional[str] = None
    name: Optional[str] = None

Values¶

When to use¶

• APIs with distinct request/response schemas
• Strict type checking for API clients
• When readOnly/writeOnly properties are heavily used

--validation (Deprecated)¶

Enables validation constraints from OpenAPI schemas.

# Deprecated
datamodel-codegen --input openapi.yaml --output models.py --validation

# Recommended
datamodel-codegen --input openapi.yaml --output models.py --field-constraints

See Field Constraints for details.

Common Patterns¶

Pattern 1: Basic API models¶

For simple APIs where you only need schema models:

datamodel-codegen --input openapi.yaml --output models.py

Pattern 2: Full API client models¶

For generating complete models for an API client:

datamodel-codegen --input openapi.yaml --output models/ \
  --openapi-scopes schemas parameters paths \
  --use-operation-id-as-name \
  --include-path-parameters

Pattern 3: Strict request/response separation¶

For APIs with distinct input/output shapes:

datamodel-codegen --input openapi.yaml --output models/ \
  --read-only-write-only-model-type all \
  --field-constraints

Pattern 4: Versioned API structure¶

For large APIs with versioned endpoints:

datamodel-codegen --input openapi.yaml --output models/ \
  --treat-dot-as-module \
  --use-operation-id-as-name \
  --all-exports-scope recursive

OpenAPI Version Support¶

See Also¶

• CLI Reference: OpenAPI-only Options
• Field Constraints
• Module Structure and Exports
• OpenAPI Input Format