OpenAPI 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.

This page is a task-oriented guide for OpenAPI-specific generation behavior. For input format basics, see Generate from OpenAPI. For every flag, choice, and generated example, see CLI Reference: OpenAPI-only Options.

Quick Overview¶

--openapi-scopes¶

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

The api scope is available for OpenAPI input only; AsyncAPI input with api stops with an error. AsyncAPI input does not read the other scopes either: it generates models from every location that holds a schema.

Default behavior (schemas only)¶

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

Generates models only from #/components/schemas.

Generate all API declarations¶

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

The api scope collects component schemas, typed parameter/request-body/response/header components, root paths, webhooks, reusable Path Items, and callbacks. It includes all request and response media, response headers, and applicable multipart encoding headers. OpenAPI version rules determine which declarations apply. Repeated references share one declaration's generated models, and callback cycles terminate without expanding models indefinitely.

Parameters generate individual schema types, including path parameters regardless of --include-path-parameters. The legacy aggregate parameter wrapper is specific to the parameters scope without api.

Parameter schemas (path, query, header, and cookie parameters) that would be emitted as root models are emitted exactly as --use-type-alias emits them, for every output model type and option combination: type LimitParameter = Annotated[int, Field(ge=1, le=100)] on Python 3.12+ and TypeAliasType below 3.12. Object parameters stay models. Anything that references a parameter schema, including another schema, references its alias. An alias has no default value, so the model no longer applies a parameter schema's scalar default. Component schemas, response headers, and the other scopes keep their usual models.

Adding other scopes alongside api does not repeat schema generation. --openapi-include-paths filters root paths and their reachable callbacks; webhooks and standalone components retain their declarations.

Use standard JSON Pointer escaping in references: ~1 represents a slash in a key and ~0 represents a tilde. API scope rejects malformed or ambiguous pointer spellings. An API with no model declarations emits no model artifact and preserves an existing output file. Explicit model metadata can still describe an empty inventory.

For Python generation, pass openapi_scopes=[OpenAPIScope.Api] to generate() or GenerateConfig. Direct parser consumers use datamodel_code_generator.parser.openapi_scope.ApiOpenAPIParser with an OpenAPIParserConfig that explicitly includes OpenAPIScope.Api. Existing scopes continue to use OpenAPIParser; the default remains schemas.

Include operation schemas¶

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

Also generates models from operation request bodies and responses.

Include operation parameter models¶

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

Also generates a query parameter model for each operation that has query parameters. Add --include-path-parameters to include URL path parameters in these models. Parameters can be declared inline or referenced from #/components/parameters. Unreferenced entries in components.parameters do not generate standalone models, and the parameters scope alone does not select operations.

When to use each scope¶

--include-path-parameters¶

Includes path parameters as fields in generated operation parameter models. Use this with --openapi-scopes paths parameters.

OpenAPI Example¶

openapi: "3.0.3"
info:
  title: Orders API
  version: "1.0"
paths:
  /users/{user_id}/orders/{order_id}:
    get:
      operationId: getOrder
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
        - name: order_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: No content

Without --include-path-parameters¶

Only query parameters are included in operation parameter models. This example has only path parameters, so it does not generate a parameter model without the flag.

With --include-path-parameters¶

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

class GetOrderParameters(BaseModel):
    user_id: str
    order_id: int

When to use¶

• Building request validation models that include URL parameters
• Grouping query and URL path parameters in one operation parameter model

--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 request/response model variants for properties marked as readOnly or writeOnly in OpenAPI.

See CLI Reference: --read-only-write-only-model-type for the full option reference.

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 request-response¶

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

class UserRequest(BaseModel):
    """For requests - excludes readOnly fields."""

    password: Optional[str] = None
    name: Optional[str] = None


class UserResponse(BaseModel):
    """For responses - excludes writeOnly fields."""

    id: Optional[int] = None
    name: Optional[str] = None

Use all instead of request-response when you also need the base model with all fields.

With request-response, a parameter model of --openapi-scopes parameters names the Request variants of the models its parameters use, such as filter: UserRequest | None = None, as a request sends its parameters.

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 request-response \
  --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