OpenAPITools / OpenAPITools/openapi-generator

[BUG] I write component object of OAS3 to external file. But error occured. Why?

Open
#3,347 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)?
  • What's the version of OpenAPI Generator used?
  • Have you search for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Bounty to sponsor the fix (example)
Description

I write component object of OAS3 to external file.
I execute validate command for OAS3 file, but the following error occured.

Errors:
	-attribute paths.'/pets'(post).responses.default.content.schema.#/components/schemas/Error is missing
	-attribute paths.'/pets/{petId}'(get).responses.200.content.schema.#/components/schemas/Pets is missing
	-attribute components.$ref is unexpected
	-attribute paths.'/pets'(get).responses.default.content.schema.#/components/schemas/Error is missing
	-attribute paths.'/pets'(get).responses.200.content.schema.#/components/schemas/Pets is missing
	-attribute paths.'/pets/{petId}'(get).responses.default.content.schema.#/components/schemas/Error is missing
openapi-generator version

v 4.0.3

OpenAPI declaration file content or url

petstore-parent.yaml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - animals
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  $ref: "./petstore-child.yaml"

petstore-child.yaml

schemas:
  Pet:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      tag:
        type: string
  Pets:
    type: array
    items:
      $ref: "#/schemas/Pet"
  Error:
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string

Command line used for generation
$  java --version
openjdk 11.0.3 2019-04-16
OpenJDK Runtime Environment (build 11.0.3+7-Ubuntu-1ubuntu218.04.1)
OpenJDK 64-Bit Server VM (build 11.0.3+7-Ubuntu-1ubuntu218.04.1, mixed mode, sharing)

$ java -jar ../openapi-generator-cli-4.0.3.jar validate -i petstore-parent.yaml 
Validating spec (petstore-parent.yaml)
Errors:
	-attribute paths.'/pets'(post).responses.default.content.schema.#/components/schemas/Error is missing
	-attribute paths.'/pets/{petId}'(get).responses.200.content.schema.#/components/schemas/Pets is missing
	-attribute components.$ref is unexpected
	-attribute paths.'/pets'(get).responses.default.content.schema.#/components/schemas/Error is missing
	-attribute paths.'/pets'(get).responses.200.content.schema.#/components/schemas/Pets is missing
	-attribute paths.'/pets/{petId}'(get).responses.default.content.schema.#/components/schemas/Error is missing


Question

Why did the error occur?
ReDoc can start HTTP server from above yaml file.

$ npx redoc-cli --version
0.8.4
$ npx redoc-cli serve petstore-parent.yaml 

image

Are above yaml file correct as OAS3?

Extra

The following yaml file is valid according to validate command of OpenAPI Generator.
Why did no error occur ?

petstore-parent.yaml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "./petstore_child.yaml#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "./petstore_child.yaml#/components/schemas/Error"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "./petstore_child.yaml#/components/schemas/Error"
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - animals
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "./petstore_child.yaml#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "./petstore_child.yaml#/components/schemas/Error"

petstore-child.yaml

components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

By the way I issued to https://github.com/OAI/OpenAPI-Specification/issues/1972 .

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

Start with the validate command in OpenAPI Generator 4.0.3 and reproduce the result using petstore-parent.yaml together with petstore-child.yaml. Compare that behavior with the second external-reference example and the reported ReDoc behavior; done means the validator's expected handling of these OAS3 files is established and covered by a regression test.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.