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