Override Generated Names

Speakeasy uses your OpenAPI schema to infer names for class types, methods, and parameters. However, you can override these names to tailor the generated SDK to your preferences.

Usage

The x-speakeasy-name-override extension can be used to override the name of a class, method, or parameter. We'll detail the various locations this extension can be placed in your OpenAPI schema to override these names at different scopes (globally vs. per operation/parameter) in the following sections.

Method Names

The x-speakeasy-name-override extension may override the generated name for the method generated from an operation. This extension may be used globally if placed at the root of the OpenAPI schema, where all methods with an operationId that match the provided operationId regex will be overridden with methodNameOverride.

openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
security:
  - basicAuth: []
x-speakeasy-name-override:
  - operationId: get*
    methodNameOverride: get
  - operationId: post*
    methodNameOverride: create
paths:
  /test:
    get:
      operationId: getTest
      responses:
        '200':
          description: OK
    post:
        operationId: postTest
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
        responses:
            '200':
            description: OK
...

Since getTest and postTest match the get* and post* regexes defined by the global x-speakeasy-name-override extension, these method names will be generated as get and create, respectively.

Alternatively, x-speakeasy-name-override may be placed at the operation level, where it will override the generated name for the method pertaining only to that operation. This can be combined with the global extension above and will take precedence over it. Consider the same schema shown above but with an operation-level extension added to the get operation:

...
    get:
      operationId: getTest
      x-speakeasy-name-override: getRandomTest
      responses:
        '200':
          description: OK
...

Now, postTest would still be generated as create as before, but getTest would be generated as getRandomTest.

Parameter Names

The x-speakeasy-name-override extension may override the generated name for the parameters generated from an operation. This extension may be used globally if placed at the root of the OpenAPI schema, where all parameters with a name that match the provided parameterName regex will be overridden with parameterNameOverride.

openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
security:
  - basicAuth: []
x-speakeasy-name-override:
  - parameterName: test*
    parameterNameOverride: testIdentifier
paths:
  /test:
    get:
      operationId: getTest
      parameters:
        - in: query
          name: testId
          schema:
            type: integer
      responses:
        '200':
          description: OK
  /test/{testCategory}/count:
    get:
      operationId: getTestCountByCategory
      parameters:
        - in: path
          name: testCategory
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          description: OK
...

Since testId and testCategory match the test* regex defined by the global x-speakeasy-name-override extension, these parameter names will both be generated as testIdentifier across methods.

Alternatively, x-speakeasy-name-override may be placed at the parameter level, where it will override the generated name for a single parameter. This can be combined with the global extension above and will take precedence over it. Consider the same schema shown above but with a parameter-level extension added to the testCategory parameter:

...
  /test/{testCategory}/count:
    get:
      operationId: getTestCountByCategory
      parameters:
        - in: path
          name: testCategory
          x-speakeasy-name-override: testCategoryIdentifier
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          description: OK
...

Now, testId would still be generated as testIdentifier as before, but testCategory would be generated as testCategoryIdentifier.

Class Names

The x-speakeasy-name-override extension may override the generated name for the class generated from a schema. This extension can only be used within a schema block for an object.

openapi: 3.1.0
info:
  title: Test
  version: 0.0.1
servers:
  - url: https://httpbin.org
security:
  - basicAuth: []
paths:
  /test:
    get:
      operationId: getTest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: Res
                x-speakeasy-name-override: TestResponse # The extension added at the schema level will override the generated class name for an object schema
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

The class generated for the getTest method's response will be named TestResponse.