OpenAPITools / OpenAPITools/openapi-generator
[BUG] I write component object of OAS3 to external file. But error occured. Why?
Nobody has claimed this yet.
- 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

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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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