OpenAPITools / OpenAPITools/openapi-generator

[REQ] Use Quicktype for models where possible

Open
#2,108 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Is your feature request related to a problem? Please describe.

The model generators in both openapi-generator and swagger-codegen are inherently deficient, having minimal coverage for the swagger 3.0 specification. The deficiencies I'm referring to are related to the following specs

  • anyOf
  • allOf

I've tested my schemas against both swagger generators and then quicktype. Please see the following models generated from an anyOf type from both openapi-generator and quicktype.

$ openapi-generator version
4.0.0-beta

See this gist

Notes

  • I had to do some hacking so codegens wouldn't break (despite being valid OAS 3.0) ... swagger/OAS codegens don't like it when you have an anyOf type nested inside an object, so you have to create a special ref for the anyOf case, and create a reference for it, in my case I called it a "variant" ( neither swagger's nor openapi's codegens work here)
  • While I used swift as an example, I tested every language in Quicktype supports against both swagger codegens (openapi-generator and swagger-codegen), with equally unusable results. Some generators act blind, others produce code that will break. Quicktype consistently produces code that is up to spec.

Describe the solution you'd like

Use quicktype for model generation where possible.

Describe alternatives you've considered

  • Writing a script to exploit openapi-generator's http handler generation, whilst nuking it's faulty models, using Quicktype to generate consistent models, and utilizing a json map to text replace openapi-generator's classes and json encoding/decoding methods inside API handlers with quicktypes' models.
  • Abandoning swagger codegens altogether and writing my own codegens for http handling and using quicktype for model generation
  • Quicktype does deep model generation, following each reference, as opposed to generating new models for each $ref, as swagger codegen does. However, the result is the same in the end.

Additional context

Struggling to get any swagger codegens working to specification, seems that quicktype produces consistent models, and since swagger is right-compatible with json-schemas, don't see why this wouldn't be a good solution.

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 reviewing the model generators in openapi-generator and swagger-codegen, then compare their handling of anyOf and allOf with the linked Quicktype examples. Done would require a defined integration scope and evidence that generated models follow the OpenAPI cases described.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.