swagger-api / swagger-api/swagger-codegen

Editor not catching $ref error

Open
#9,599 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mustache
Stars
17.8k
Forks
6k
PR merge metrics
No merged PRs in 30d

Description

System information
  • OS: macOS 10.14
  • Browser: Chrome
  • Version: 75.0
  • Swagger/OpenAPI version: OpenAPI 3.0
  • Found in the online swagger editor
    https://editor.swagger.io/
Example yaml to reproduce the error
module:
    post:
      tags:
      - module
      summary: Create a module
      operationId: createModule
      security:
        - TokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BaseModule'
                - $ref: '#/components/schemas/FullModule'
      responses:
        200:
          description: "Success: module created"
...
components:
  schemas:
    BaseModule:
      description: Basic information about a model
      type: object
      properties:
        moduleId:
          type: integer
          format: int64
        moduleName:
          type: string
        details:
          type: string
        numberOfWords:
          type: integer
          format: int32
          example: 10
        parent:
          type: integer
          format: int64
        child:
          type: integer
          format: int64
      required:
        - moduleName

    FullModule:
      allOf:
        - $ref: '#/components/schemas/InfoModule'
        - type: object
          properties:
            words:
              type: array
              items:
                $ref: '#/components/schemas/Dictionary'
            quiz:
              type: array
              items:
                $ref: '#/components/schemas/Quiz'
      required:
        - words
Expected behavior
  • The code above is marked as valid by the online editor as it appears to cause errors with Codegen
  • utilizing the Codegen functionality to build a python-flask server stub I get the following error
There was an error generating the servers python-flask code. Please ensure that the definition and all external refs (inc. domains) are valid.
  • I tried to generate the code locally with swagger-codegen generate -i Documents/asltutor.ymal -l python-flask -o Desktop and got the following error:
java.lang.NullPointerException
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromProperty(DefaultCodegenConfig.java:1685)
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromRequestBody(DefaultCodegenConfig.java:2589)
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromOperation(DefaultCodegenConfig.java:2102)
	at io.swagger.codegen.v3.DefaultGenerator.processOperation(DefaultGenerator.java:901)
	at io.swagger.codegen.v3.DefaultGenerator.processPaths(DefaultGenerator.java:828)
	at io.swagger.codegen.v3.DefaultGenerator.generateApis(DefaultGenerator.java:462)
	at io.swagger.codegen.v3.DefaultGenerator.generate(DefaultGenerator.java:776)
	at io.swagger.codegen.v3.cli.cmd.Generate.run(Generate.java:342)
	at java.lang.Thread.run(Thread.java:748)
Exception in thread "Thread-1" java.lang.RuntimeException: Could not process operation:
  Tag: class Tag {
    name: module
    description: null
    externalDocs: null
}
  Operation: create_module
  Resource: post /modules
  Exception: null
	at io.swagger.codegen.v3.DefaultGenerator.processOperation(DefaultGenerator.java:926)
	at io.swagger.codegen.v3.DefaultGenerator.processPaths(DefaultGenerator.java:828)
	at io.swagger.codegen.v3.DefaultGenerator.generateApis(DefaultGenerator.java:462)
	at io.swagger.codegen.v3.DefaultGenerator.generate(DefaultGenerator.java:776)
	at io.swagger.codegen.v3.cli.cmd.Generate.run(Generate.java:342)
	at java.lang.Thread.run(Thread.java:748)
Caused by: java.lang.NullPointerException
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromProperty(DefaultCodegenConfig.java:1685)
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromRequestBody(DefaultCodegenConfig.java:2589)
	at io.swagger.codegen.v3.generators.DefaultCodegenConfig.fromOperation(DefaultCodegenConfig.java:2102)
	at io.swagger.codegen.v3.DefaultGenerator.processOperation(DefaultGenerator.java:901)
	... 5 more
  • The error appears to be coming from the following section:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/BaseModule'
                - $ref: '#/components/schemas/FullModule'
  • change to the following and code can be generated without error:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FullModule'
Additional thoughts
  • I suspect the code generator is working as expected but the online editor is not catching the implementation error and states that the code is valid
  • strangely the code-gen error does not occur when building a spring, inflector or aspnetcore server stub. No idea why.

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 supplied OpenAPI YAML in the online editor, then compare its validation with the python-flask generation failure. Start with the reported DefaultCodegenConfig.java and DefaultGenerator.java stack-trace locations; done means the editor and generator agree on the oneOf case and the failure is covered by a reproducible check.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.