Skip to content

📘 OpenAPI-only Options

📋 Options

Option Description
--include-path-parameters Include OpenAPI path parameters in generated parameter model...
--openapi-scopes Specify OpenAPI scopes to generate (schemas, paths, paramete...
--read-only-write-only-model-type Generate separate request and response models for readOnly/w...
--use-operation-id-as-name Use OpenAPI operationId as the generated function/class name...
--use-status-code-in-response-name Include HTTP status code in response model names.
--validation Enable validation constraints (deprecated, use --field-const...

--include-path-parameters

Include OpenAPI path parameters in generated parameter models.

The --include-path-parameters flag adds path parameters (like /users/{userId}) to the generated request parameter models. By default, only query parameters are included. Use this with --openapi-scopes parameters to generate parameter models that include both path and query parameters.

See also: OpenAPI-Specific Options

Usage

datamodel-codegen --input schema.json --include-path-parameters --openapi-scopes schemas paths parameters # (1)!
  1. --include-path-parameters - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: API with Path Parameters
paths:
  /users/{userId}/posts/{postId}:
    get:
      summary: Get a specific post by user
      operationId: getUserPost
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: postId
          in: path
          required: true
          schema:
            type: string
        - name: includeComments
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A post
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Post"
components:
  schemas:
    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        content:
          type: string

Output:

# generated by datamodel-codegen:
#   filename:  include_path_parameters.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Post(BaseModel):
    id: str | None = None
    title: str | None = None
    content: str | None = None


class UsersUserIdPostsPostIdGetParameters(BaseModel):
    userId: int
    postId: str
    includeComments: bool | None = None

--openapi-scopes

Specify OpenAPI scopes to generate (schemas, paths, parameters).

The --openapi-scopes flag configures the code generation behavior.

See also: OpenAPI-Specific Options

Usage

datamodel-codegen --input schema.json --openapi-scopes paths schemas # (1)!
  1. --openapi-scopes - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
  description: |
    This description is for testing
    multi-line
    description

servers:
  - url: http://petstore.swagger.io/v1
security:
  - BearerAuth: []
paths:
  /pets:
    $ref: '#/components/pathItems/Pets'
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      summary: update a pet
      tags:
        - pets
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetForm'
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
  /food:
    post:
      summary: Create a food
      tags:
        - pets
      requestBody:
        required: true
        content:
          application/problem+json:
            schema:
              type: string
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/problem+json:
              schema:
                type: string
  /food/{food_id}:
    get:
      summary: Info for a specific pet
      operationId: showFoodById
      tags:
        - foods
      parameters:
        - name: food_id
          in: path
          description: The id of the food to retrieve
          schema:
            type: string
        - name: message_texts
          in: query
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: integer
              examples:
                example-1:
                  value:
                    - 0
                    - 1
                    - 3
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
  /foo:
    get:
      tags:
        - foo
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
    parameters:
    - $ref: '#/components/parameters/MyParam'
  /bar:
    post:
      summary: Create a bar
      tags:
        - bar
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PetForm'
  /user:
    get:
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  name:
                    type: string
                  age:
                    type: string
                required:
                  - name
                  - timestamp
    post:
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timestamp:
                  type: string
                  format: date-time
                name:
                  type: string
                age:
                  type: string
              required:
                - name
                - timestamp
      responses:
        '201':
          description: OK
  /users:
    get:
      tags:
        - user
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    timestamp:
                      type: string
                      format: date-time
                    name:
                      type: string
                    age:
                      type: string
                  required:
                    - name
                    - timestamp
    post:
      tags:
        - user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  name:
                    type: string
                  age:
                    type: string
                required:
                  - name
                  - timestamp
      responses:
        '201':
          description: OK
components:
  parameters:
    MyParam:
      name: foo
      in: query
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    PetForm:
      title: PetForm
      type: object
      properties:
        name:
          type: string
        age:
          type: integer
  pathItems:
    Pets:
      get:
        summary: List all pets
        operationId: listPets
        tags:
          - pets
        security: []
        parameters:
          - name: limit
            in: query
            description: How many items to return at one time (max 100)
            required: false
            schema:
              default: 0
              type: integer
              format: int32
          - name: HomeAddress
            in: query
            required: false
            schema:
              default: 'Unknown'
              type: string
          - name: kind
            in: query
            required: false
            schema:
              default: dog
              type: string
        responses:
          '200':
            description: A paged array of pets
            headers:
              x-next:
                description: A link to the next page of responses
                schema:
                  type: string
            content:
              application/json:
                schema:
                  type: array
                  items:
                  - $ref: "#/components/schemas/Pet"
          default:
            description: unexpected error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"
      post:
        summary: Create a pet
        tags:
          - pets
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetForm'
        responses:
          '201':
            description: Null response
          default:
            description: unexpected error
            content:
              application/json:
                schema:
                  $ref: "#/components/schemas/Error"

Output:

# generated by datamodel-codegen:
#   filename:  body_and_parameters.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from datetime import datetime

from pydantic import BaseModel


class Pet(BaseModel):
    id: int
    name: str
    tag: str | None = None


class Error(BaseModel):
    code: int
    message: str


class PetForm(BaseModel):
    name: str | None = None
    age: int | None = None


class PetsGetResponse(BaseModel):
    __root__: list[Pet]


class FoodFoodIdGetResponse(BaseModel):
    __root__: list[int]


class UserGetResponse(BaseModel):
    timestamp: datetime
    name: str
    age: str | None = None


class UserPostRequest(BaseModel):
    timestamp: datetime
    name: str
    age: str | None = None


class UsersGetResponseItem(BaseModel):
    timestamp: datetime
    name: str
    age: str | None = None


class UsersGetResponse(BaseModel):
    __root__: list[UsersGetResponseItem]


class UsersPostRequestItem(BaseModel):
    timestamp: datetime
    name: str
    age: str | None = None


class UsersPostRequest(BaseModel):
    __root__: list[UsersPostRequestItem]

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

Generate separate request and response models for readOnly/writeOnly fields.

The --read-only-write-only-model-type option controls how models with readOnly or writeOnly properties are generated. The 'request-response' mode creates separate Request and Response variants for each schema that contains readOnly or writeOnly fields, allowing proper type validation for API requests and responses without a shared base model.

See also: OpenAPI-Specific Options

Usage

datamodel-codegen --input schema.json --output-model-type pydantic_v2.BaseModel --read-only-write-only-model-type request-response # (1)!
  1. --read-only-write-only-model-type - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  title: Read Only Write Only Test API
  version: "1.0"
paths: {}
components:
  schemas:
    User:
      type: object
      required:
        - id
        - name
        - password
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
        password:
          type: string
          writeOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        secret_token:
          type: string
          writeOnly: true

Output:

# generated by datamodel-codegen:
#   filename:  read_only_write_only.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import AwareDatetime, BaseModel


class UserRequest(BaseModel):
    name: str
    password: str
    secret_token: str | None = None


class UserResponse(BaseModel):
    id: int
    name: str
    created_at: AwareDatetime | None = None

--use-operation-id-as-name

Use OpenAPI operationId as the generated function/class name.

The --use-operation-id-as-name flag configures the code generation behavior.

See also: OpenAPI-Specific Options

Usage

datamodel-codegen --input schema.json --use-operation-id-as-name --openapi-scopes paths schemas parameters # (1)!
  1. --use-operation-id-as-name - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          default: 1
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Users:
      type: array
      items:
        required:
          - id
          - name
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
          tag:
            type: string
    Id:
      type: string
    Rules:
      type: array
      items:
        type: string
    Error:
      description: error result
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    apis:
      type: array
      items:
        type: object
        properties:
          apiKey:
            type: string
            description: To be used as a dataset parameter value
          apiVersionNumber:
            type: string
            description: To be used as a version parameter value
          apiUrl:
            type: string
            format: uri
            description: "The URL describing the dataset's fields"
          apiDocumentationUrl:
            type: string
            format: uri
            description: A URL to the API console for each API
    Event:
      type: object
      description: Event object
      properties:
        name:
          type: string
    Result:
        type: object
        properties:
          event:
            $ref: '#/components/schemas/Event'

Output:

# generated by datamodel-codegen:
#   filename:  api.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import AnyUrl, BaseModel, Field


class Pet(BaseModel):
    id: int
    name: str
    tag: str | None = None


class Pets(BaseModel):
    __root__: list[Pet]


class User(BaseModel):
    id: int
    name: str
    tag: str | None = None


class Users(BaseModel):
    __root__: list[User]


class Id(BaseModel):
    __root__: str


class Rules(BaseModel):
    __root__: list[str]


class Error(BaseModel):
    code: int
    message: str


class Api(BaseModel):
    apiKey: str | None = Field(
        None, description='To be used as a dataset parameter value'
    )
    apiVersionNumber: str | None = Field(
        None, description='To be used as a version parameter value'
    )
    apiUrl: AnyUrl | None = Field(
        None, description="The URL describing the dataset's fields"
    )
    apiDocumentationUrl: AnyUrl | None = Field(
        None, description='A URL to the API console for each API'
    )


class Apis(BaseModel):
    __root__: list[Api]


class Event(BaseModel):
    name: str | None = None


class Result(BaseModel):
    event: Event | None = None


class ListPetsParametersQuery(BaseModel):
    limit: int | None = None

--use-status-code-in-response-name

Include HTTP status code in response model names.

The --use-status-code-in-response-name flag includes the HTTP status code in generated response model class names. Instead of generating ambiguous names like ResourceGetResponse, ResourceGetResponse1, ResourceGetResponse2, it generates clear names like ResourceGetResponse200, ResourceGetResponse400, ResourceGetResponseDefault.

Usage

datamodel-codegen --input schema.json --use-status-code-in-response-name --openapi-scopes schemas paths # (1)!
  1. --use-status-code-in-response-name - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Status Code Response Name Test API
paths:
  /resource:
    get:
      summary: Get a resource
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
        '400':
          description: Bad request error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
        'default':
          description: Unexpected error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

Output:

# generated by datamodel-codegen:
#   filename:  use_status_code_in_response_name.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class ResourceGetResponse200(BaseModel):
    id: int | None = None
    name: str | None = None


class ResourceGetResponse400(BaseModel):
    error: str | None = None
    code: int | None = None


class ResourceGetResponseDefault(BaseModel):
    message: str | None = None

--validation

Enable validation constraints (deprecated, use --field-constraints).

The --validation flag configures the code generation behavior.

Deprecated: Use --field-constraints instead

See also: Field Constraints, OpenAPI-Specific Options

Usage

datamodel-codegen --input schema.json --validation # (1)!
  1. --validation - the option documented here
Examples

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          default: 1
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Users:
      type: array
      items:
        required:
          - id
          - name
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
          tag:
            type: string
    Id:
      type: string
    Rules:
      type: array
      items:
        type: string
    Error:
      description: error result
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    apis:
      type: array
      items:
        type: object
        properties:
          apiKey:
            type: string
            description: To be used as a dataset parameter value
          apiVersionNumber:
            type: string
            description: To be used as a version parameter value
          apiUrl:
            type: string
            format: uri
            description: "The URL describing the dataset's fields"
          apiDocumentationUrl:
            type: string
            format: uri
            description: A URL to the API console for each API
    Event:
      type: object
      description: Event object
      properties:
        name:
          type: string
    Result:
        type: object
        properties:
          event:
            $ref: '#/components/schemas/Event'

Output:

# generated by datamodel-codegen:
#   filename:  api.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import AnyUrl, BaseModel, Field


class Pet(BaseModel):
    id: int
    name: str
    tag: str | None = None


class Pets(BaseModel):
    __root__: list[Pet]


class User(BaseModel):
    id: int
    name: str
    tag: str | None = None


class Users(BaseModel):
    __root__: list[User]


class Id(BaseModel):
    __root__: str


class Rules(BaseModel):
    __root__: list[str]


class Error(BaseModel):
    code: int
    message: str


class Api(BaseModel):
    apiKey: str | None = Field(
        None, description='To be used as a dataset parameter value'
    )
    apiVersionNumber: str | None = Field(
        None, description='To be used as a version parameter value'
    )
    apiUrl: AnyUrl | None = Field(
        None, description="The URL describing the dataset's fields"
    )
    apiDocumentationUrl: AnyUrl | None = Field(
        None, description='A URL to the API console for each API'
    )


class Apis(BaseModel):
    __root__: list[Api]


class Event(BaseModel):
    name: str | None = None


class Result(BaseModel):
    event: Event | None = None