OpenAPITools / OpenAPITools/openapi-generator

[BUG] Defining a type in components/schemas/ in two separate referenced yaml fails

Open
#13,612 0 comments 4 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 have a REST API described as openapi: 3.0.1 spec, and split across several files included via refs.
Both included files define a components/schemas/JsonApiResponse. The validation shows an error that a defined type components/schemas/JsonApiResponse_1 can't be found, which could be either on the spec side or how openapi-generator handles this case.

Specifically, one of the duplicate names seems to be renamed to JsonApiResponse_1 and then further in the process validation complains that this renamed thing is not in the original yaml file. Which of course it isn't, so the openapi-generator-cli seems to have "forgotten" that it renamed it.

I slashed the complex REST API (not under my control) to a small example, but I can't nail the root cause.

So index.yaml has two paths, which reference into separate yaml files:

paths:
  /entities/shares:
    $ref: 'entities.yaml#/paths/%2Fentities%2Fshares'
  /users:
    $ref: 'users.yaml#/paths/%2Fusers'

the individual entities.yaml and users.yaml both have (local?) definition of

components:
  schemas:
    JsonApiResponse:
      title: 'JsonApiResponse'
      type: object

and use them in specifying the content: of a response::

              schema:
                allOf:
                  - $ref: '#/components/schemas/JsonApiResponse'
                  - type: object

Specifically, the issue appears only if the two definitions of components/schemas/JsonApiResponse differ,
for that it is sufficient if one is called title: 'JsonApiResponseX', or (as in the uploaded examples) one has a properties: section and the other doesn't.

The error thrown in the validation are:

docker run --rm -v $PWD:/local openapitools/openapi-generator-cli validate -i /local/index.yaml
Validating spec (/local/index.yaml)
[main] WARN  io.swagger.v3.parser.OpenAPIV3Parser - Exception while resolving:
java.lang.RuntimeException: Could not find components/schemas/JsonApiResponse_1 in contents of ./users.yaml
	at io.swagger.v3.parser.ResolverCache.loadRef(ResolverCache.java:186)
	at io.swagger.v3.parser.processors.ExternalRefProcessor.processRefToExternalSchema(ExternalRefProcessor.java:88)
	at io.swagger.v3.parser.processors.SchemaProcessor.processReferenceSchema(SchemaProcessor.java:236)
	at io.swagger.v3.parser.processors.SchemaProcessor.processComposedSchema(SchemaProcessor.java:152)
	at io.swagger.v3.parser.processors.SchemaProcessor.processSchemaType(SchemaProcessor.java:73)
	at io.swagger.v3.parser.processors.SchemaProcessor.processSchema(SchemaProcessor.java:62)
	at io.swagger.v3.parser.processors.ResponseProcessor.processResponse(ResponseProcessor.java:56)
	at io.swagger.v3.parser.processors.OperationProcessor.processOperation(OperationProcessor.java:86)
	at io.swagger.v3.parser.processors.PathsProcessor.processPaths(PathsProcessor.java:88)
	at io.swagger.v3.parser.OpenAPIResolver.resolve(OpenAPIResolver.java:72)
	at io.swagger.v3.parser.OpenAPIResolver.resolve(OpenAPIResolver.java:59)
	at io.swagger.v3.parser.OpenAPIV3Parser.resolve(OpenAPIV3Parser.java:226)
	at io.swagger.v3.parser.OpenAPIV3Parser.readContents(OpenAPIV3Parser.java:178)
	at io.swagger.v3.parser.OpenAPIV3Parser.readLocation(OpenAPIV3Parser.java:94)
	at io.swagger.parser.OpenAPIParser.readLocation(OpenAPIParser.java:16)
	at org.openapitools.codegen.cmd.Validate.execute(Validate.java:52)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: ./users.yaml#/components/schemas/JsonApiResponse_1
[main] WARN  o.o.codegen.utils.ModelUtils - Failed to get the schema name: ./users.yaml#/components/schemas/JsonApiResponse_1
Errors:
	- Could not find components/schemas/JsonApiResponse_1 in contents of ./users.yaml
Warnings: 
	- Unused model: JsonApiResponse_1
openapi-generator version
docker run openapitools/openapi-generator-cli version
6.2.1-SNAPSHOT
openapitools/openapi-generator-cli                         latest                  31030ce55950   17 hours ago    323MB

I also tested swagger-codegen which also complains about Could not find components/schemas/JsonApiResponse_1 in contents of ./users.yaml.

docker run --rm swaggerapi/swagger-codegen-cli-v3 version
3.0.35
OpenAPI declaration file content or url

The YAML files are attached.
entities.yaml.txt
index.yaml.txt
users.yaml.txt

Generation Details
docker run --rm -v $PWD:/local openapitools/openapi-generator-cli validate -i /local/index.yaml
Related issues/PRs

I am unsure what search terms to use, as I am not an expert in openapi.

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 by running the documented openapitools/openapi-generator-cli validate command against index.yaml, with entities.yaml and users.yaml beside it, and compare the duplicated JsonApiResponse references. Trace how the external references are resolved and renamed; done means validation no longer looks for JsonApiResponse_1 in the wrong YAML file.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, 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.