OpenAPITools / OpenAPITools/openapi-generator

[BUG] Generation with `--global-property` results in unexpected changes

Open
#9,599 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Bug Report Checklist
  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator (example)?
  • Have you tested with the latest master to confirm the issue still exists?
  • Have you searched for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description

I'm using python-flask templates and attempting to generate only specific files at a given time in CI.

When using --global-property supportedFiles to generate, it will generate an openapi.yaml file that is missing complex examples.
When using --global-property supportedFiles,apis to generate, it will generate an openapi.yaml WITH the complext examples.

What do I mean by complex examples?

example: simple

would still be there, but

example:
  foo: bar
  baz: blerg

would be missing.

openapi-generator version

5.0.0
5.1.1 (also omits title, which was added between the two versions)

OpenAPI declaration file content or url
openapi: 3.0.0
info:
  title: Missing Example prototype
  version: 0.1.0
  description: Shows that generating oas with supportingFiles vs supportingFiles,apis gives different results
servers:
  - url: 'http://localhost:5000'
paths:
  '/v0/prototypes/{prototypeId}':
    parameters:
      - $ref: '#/components/parameters/prototypeId'
    post:
      operationId: createPrototype
      summary: Create a Prototype
      description: Creates a new instance of a `Prototype`.
      tags:
        - prototypes
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: CreatePrototypeRequest
              description: Request body.
              properties:
                prototype:
                  $ref: '#/components/schemas/Prototype'
              required:
                - prototype
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prototype'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
        '598':
          $ref: '#/components/responses/598'
    get:
      operationId: getPrototype
      summary: Get a Prototype
      description: Gets the details of a single instance of a `Prototype`.
      tags:
        - prototypes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prototype'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
        '598':
          $ref: '#/components/responses/598'
    patch:
      operationId: updatePrototype
      summary: Update a Prototype
      description: Updates an existing `Prototype`.
      tags:
        - prototypes
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/Prototype'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prototype'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '415':
          $ref: '#/components/responses/415'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
        '598':
          $ref: '#/components/responses/598'
    delete:
      operationId: deletePrototype
      summary: Delete a Prototype
      description: Deletes an existing `Prototype`.
      tags:
        - prototypes
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
        '598':
          $ref: '#/components/responses/598'
components:
  parameters:
    prototypeId:
      name: prototypeId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 128
        example: Kmz93oJDnPRXGuHZWjUEZEUYT4v1
  schemas:
    Prototype:
      title: Prototype
      type: object
      description: An prototype.
      properties:
        name:
          type: string
          description: |
            Unique relative resource name. The prototype ID should be that provided by the auth provider.
          readOnly: true
          pattern: '^prototypes/.{1,128}$'
          example: prototypes/Kmz93oJDnPRXGuHZWjUEZEUYT4v1
        email:
          type: string
          format: email
          nullable: true
          example: example@example.com
        firstName:
          type: string
          nullable: true
          maxLength: 100
          example: John
        lastName:
          type: string
          nullable: true
          maxLength: 100
          example: Doe
        phoneNumber:
          type: string
          description: Phone number in E.164 normalized format.
          nullable: true
          pattern: '^\+[1-9]\d{1,14}$'
          example: '+12223334444'
        phoneNumberLegacy:
          type: string
          description: Legacy phone numbers in any format.
          readOnly: true
          nullable: true
          example: 222-333-4444
        birthdate:
          type: string
          format: date
          nullable: true
          example: '2020-01-01'
        createTime:
          type: string
          format: date-time
          readOnly: true
          example: '2020-04-06T00:08:42Z'
        updateTime:
          type: string
          format: date-time
          readOnly: true
          example: '2020-10-22T04:46:10Z'
    Problem:
      title: Problem
      type: object
      description: JSON Problem (RFC 7807).
      properties:
        type:
          type: string
          format: uri-reference
          description: |
            A relative URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the recommendation in specification RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.
          default: 'about:blank'
          example: /problems/connection-error
        title:
          type: string
          description: |
            A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: Connection to database timed out
        instance:
          type: string
          format: uri-reference
          description: |
            An relative URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
          example: /problems/connection-error#token-info-read-timed-out
  responses:
    '204':
      description: No Content
    '304':
      description: Not Modified
    '400':
      description: Bad Request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '401':
      description: Unauthorized
    '403':
      description: Forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '404':
      description: Not Found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '406':
      description: Not Acceptable
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '409':
      description: Conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '412':
      description: Precondition Failed
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '413':
      description: Request Entity Too Large
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '415':
      description: Unsupported Media Type
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '428':
      description: Precondition Required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '429':
      description: Too Many Requests
    '500':
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    '502':
      description: Bad Gateway
    '503':
      description: Service Unavailable
    '504':
      description: Gateway Timeout
    '598':
      description: Network Read Timeout Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    localAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - localAuth: []
tags:
  - name: prototypes
Generation Details

To generate with only supporting files to a dir (tmp-sans-apis)

openapi-generator-cli generate -i /tmp/example.yaml -g python-flask -o tmp-sans-apis --global-property supportingFiles

To generate with only supporting files to a dir (tmp-with-apis)

openapi-generator-cli generate -i /tmp/example.yaml -g python-flask -o tmp-with-apis --global-property supportingFiles,apis
Steps to reproduce

Follow the above generation steps, then compare with diff:

To compare the generated yaml files:

diff tmp-sans-apis/openapi_server/openapi/openapi.yaml tmp-with-apis/openapi_server/openapi/openapi.yaml
Related issues/PRs

A cursory look found no issues.

Suggest a fix

I wouldn't expect a difference between the two options. Not sure where the problem would be.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the difference between --global-property supportedFiles and --global-property supportedFiles,apis using the provided OpenAPI declaration and python-flask templates. Compare the generated openapi.yaml output, focusing on complex object examples and the title; done means both generation modes preserve the same expected content.

Written by the indexing model from the issue text.

Assessment

Tech stack
flask, java, python
Domain
api, cli, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.