feat: generate const object for const schema definition

[fjodor-rybakov]

Status

READY

Description

#1849

Add new useConstForSchemaDefinition for generate const instead interface for schema definition.
For example:

#swagger api
components:
  schemas:
    InvalidRequestDataException:
      type: object
      properties:
        message:
          type: string
          const: 'Invalid data'
        code:
          type: integer
          const: 1
          description: 'Unique exception code'
      required: [ 'message', 'code' ]

With enabled useConstForSchemaDefinition i will get follow generated code

export const InvalidRequestDataExceptionValue = {
  message: 'Invalid data';
  code: 1;
} as const;
export type InvalidRequestDataException = typeof InvalidRequestDataExceptionValue;

Related PRs

List related PRs against other branches:

branch	PR
other_pr_production	link
other_pr_master	link

Todos

• Tests
• Documentation
• Changelog Entry (unreleased)

Steps to Test or Reproduce

Outline the steps to test or reproduce the PR here.

> git pull --prune
> git checkout <branch>
> grunt jasmine

[soartec-lab]

@fjodor-rybakov
Could you please explain in more detail why you want to use this in const?

[fjodor-rybakov]

@fjodor-rybakov Could you please explain in more detail why you want to use this in const?

I have some api like this:

openapi: 3.1.0
paths:
  /get-bubble-gums/{id}:
    get:
      parameters:
        - in: path
          name: id
          schema:
            type: number
      responses:
        '200':
          description: Suceess response
          content:
            application/json:
              schema:
                #some success schems
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BubbleGumIdNotFoundException'
                
components:
  schemas:
     BubbleGumIdNotFoundException:
        type: object
        properties:
          message:
            type: string
            const: 'Bubble gum not found'
          code:
            type: integer
            const: 1
            description: 'Unique exception code'
        required: [ 'message', 'code' ]

In specification I write BubbleGumIdNotFoundException constant object(all properties have const). In my code I want to get this constant object and use code property in code logic. Like:

if (response.body.code === BubbleGumIdNotFoundExceptionValue.code) {
  // do some
} else {
  // do else

[soartec-lab]

@fjodor-rybakov

good. I double-checked the specifications and understood that const definitions are declarations for managing constants like enums.

• https://json-schema.org/draft/2020-12/json-schema-validation#name-const
• Defining constant value in response OAI/OpenAPI-Specification#1313
• https://swagger.io/specification/

Please comment what you would like to change.
And please also add the following two files.

1. add test using const to default.config.ts

https://github.com/orval-labs/orval/blob/master/tests/configs/default.config.ts

2. add useConstForSchemaDefinition property to guide

https://github.com/orval-labs/orval/blob/master/docs/src/pages/reference/configuration/output.md

[fjodor-rybakov]

@fjodor-rybakov

good. I double-checked the specifications and understood that const definitions are declarations for managing constants like enums.

• https://json-schema.org/draft/2020-12/json-schema-validation#name-const
• Defining constant value in response OAI/OpenAPI-Specification#1313
• https://swagger.io/specification/

Please comment what you would like to change. And please also add the following two files.

1. add test using const to default.config.ts

https://github.com/orval-labs/orval/blob/master/tests/configs/default.config.ts

2. add useConstForSchemaDefinition property to guide

https://github.com/orval-labs/orval/blob/master/docs/src/pages/reference/configuration/output.md

1. Done
2. Done

[soartec-lab]

@fjodor-rybakov
I was wondering if this should be an option.
If all objects include const, I think it would be okay to output const as you do now, without specifying it as an option.
Can you tell me why you made it an option in the first place?

[fjodor-rybakov]

@fjodor-rybakov I was wondering if this should be an option. If all objects include const, I think it would be okay to output const as you do now, without specifying it as an option. Can you tell me why you made it an option in the first place?

Indeed, you are right, this can be made the default behavior without set useConstForSchemaDefinition. I was thinging that if I make changes, i do it with a feature flag for enable or disable my feature(Maybe this is redundant). We make set useConstForSchemaDefinition: true by default or remove useConstForSchemaDefinition option altogether. What do you think?

[soartec-lab]

@fjodor-rybakov
In my opinion, this option can be removed.
This is because this is in accordance with the OpenAPI specification, and because we want to reduce optional controls as much as possible.
I don't think it's too late to consider switching to an option again when a situation arises where you want to disable it.

[fjodor-rybakov]

@fjodor-rybakov In my opinion, this option can be removed. This is because this is in accordance with the OpenAPI specification, and because we want to reduce optional controls as much as possible. I don't think it's too late to consider switching to an option again when a situation arises where you want to disable it.

Okey, I am get rid of useConstForSchemaDefinition option

[melloware]

Running build again!

[fjodor-rybakov]

It turned out that not everything was so simple. getScalar can return value with some imported type instead const. Do you have some idea for quic fix it? @soartec-lab @melloware

[soartec-lab]

@fjodor-rybakov

Well, it seems like you need to change the output as below:

- export type StringConstValueNullable = 'string' | null | null;
+ export const StringConstValueNullable = 'string' as const;
+ export type StringConstValueNullableType = typeof StringConstValueNullable | null;

- import type { StringConstValueNullable } from './stringConstValueNullable';
+ import { StringConstValueNullable } from './stringConstValueNullable';

export const StringConstValue = {
  value: 'string',
  valueWithoutType: 'string',
  valueNullable: StringConstValueNullable,
} as const;
export type StringConst = typeof StringConstValue;

[fjodor-rybakov]

@fjodor-rybakov

Well, it seems like you need to change the output as below:

- export type StringConstValueNullable = 'string' | null | null;
+ export const StringConstValueNullable = 'string' as const;
+ export type StringConstValueNullableType = typeof StringConstValueNullable | null;

- import type { StringConstValueNullable } from './stringConstValueNullable';
+ import { StringConstValueNullable } from './stringConstValueNullable';

export const StringConstValue = {
  value: 'string',
  valueWithoutType: 'string',
  valueNullable: StringConstValueNullable,
} as const;
export type StringConst = typeof StringConstValue;

Hmm... I think some wrong in test spec const.yaml.
In follow schema valueNullable always const and at the same time type can be string and null

openapi: 3.1.0
info:
  title: Const
  version: 1.0.0
paths: {}
components:
  schemas:
    StringConst:
      type: object
      required:
        - value
        - valueWithoutType
        - valueNullable
      properties:
        value:
          type: string
          const: string
        valueWithoutType:
          const: string
        valueNullable:
          type:
            - string
            - 'null'
          const: string

In my opinion, adding nulls to types is confusing. As if constant could change...