Lessons learned from API client generation - 05 Naming conventions

Oct 1, 2022

Fourth pattern of our series: naming conventions for unnamed things. When Kiota generates models for requests bodies and responses, two cases are possible: either the type is defined in a reusable component schema, which means the component is named and Kiota can use that name for the generated model. Or the type is defined inline, in which case Kiota needs to rely on naming conventions.

paths:
  /path:
    get:
      summary: Get
      description: Get
      operationId: get
      tags:
      - api1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object # PathResponse
                properties:
                  inlineProperty:
                    type: object # PathResponseInlinePropertyModel
                    properties:
                      subInlineProp:
                        type: object # PathResponseInlinePropertyModelSubInlinePropModel
                        properties:
                          subSubInlineProp:
                            type: string
                  inlineArrayProperty:
                    type: array
                    items:
                      type: object # PathResponseInlineArrayPropertyModel
                      properties:
                        subInlineProp:
                          type: string

In the snippet above the generated types will be named according to the path segment name and according to naming suffixes always appended to the parent type name. While it works, the generator should not have the responsibility to arbitrarily define naming conventions. There should instead be a placeholder for the API owner to dictate those conventions.

Suggestions

The following snippet shows what such placeholder could look like. Additionally, linters should add rules to warn against using inline types which reduce reusability and increase maintenance burden.

x-ms-naming-conventions:
  responses:
    suffix: Response
    includePathName: true
  requestBodies:
    suffix: Request
    includePathName: true
  parameters:
    suffix: Parameter
    includePathName: true
  nestedModel:
    suffix: Model
    includeParentName: true
  composedTypeWrapper:
    suffix: Wrapper
  composedTypeMember:
    suffix: MemberModel
    includeParentName: true

Last edited Oct 24, 2022 by Vincent Biret


Tags: