openapi-generator icon indicating copy to clipboard operation
openapi-generator copied to clipboard

Published 20 hours ago • verified publisher icon OpenAPITools

[REQ] Support for OpenAPI Spec 3.1

Open westn opened this issue 3 years ago • 18 comments

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

Support for OpenAPI Spec 3.1, released last month: https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0

Describe the solution you'd like

Add support for OpenAPI Spec 3.1

Additional context

Couldn't see any other mention of this besides a short mention in #15 Another note on https://www.openapis.org/blog/2020/06/18/openapi-3-1-0-rc0-its-here which mention that the specification-change is bigger than it sounds and might break some tooling.

westn avatar Mar 25 '21 14:03 westn

We use swagger-parser to parse openapi specs. That project must implement v 3.1 spec parsing before we can implement it in the generators.

spacether avatar Apr 13 '21 23:04 spacether

https://github.com/swagger-api/swagger-parser/commits/oas3.1

darkbasic avatar Sep 10 '21 16:09 darkbasic

Any updates to share on potentially updating the generators to OAS 3.1?

cgfarmer4 avatar May 11 '22 22:05 cgfarmer4

Any updates to share on potentially updating the generators to OAS 3.1?

https://github.com/swagger-api/swagger-parser/issues/1535, there has been no update for half a year.

gunsluo avatar May 15 '22 02:05 gunsluo

OAS 3.1 support has been added to swagger-parser in https://github.com/swagger-api/swagger-parser/pull/1730

cyangle avatar May 27 '22 04:05 cyangle

What release do you aim for this to be implemented in the generator? 6.1.0?

denisgolubovic avatar Jun 13 '22 12:06 denisgolubovic

swagger-parser 2.1 has been released with OAS 3.1 support https://github.com/swagger-api/swagger-parser/releases/tag/v2.1.0

kiwisincebirth avatar Jun 16 '22 01:06 kiwisincebirth

This is a big oof on my part. I just spent a ton of time setting up an API spec for a client and used 3.1.0 and now that its all approved I need to actually program the API server and need to generate the base files from the spec. Now I find out that not only does this package not support 3.1.0 currently but I cannot seem to find any code generator that does :( big yikes! I have to figure out what my options are at this point as my spec currently makes heavy use of the type as an array not a string and I also use oneOf with "null" or a $ref throughout the whole thing which makes it a major problem to downgrade to 3.0.3 at this point.

I see that as of 27 days ago at the time of me writing this, the 3.1 spec was added to https://github.com/swagger-api/swagger-parser/issues/1535 - Does anyone have any idea when there will be a beta / snapshot release that will support 3.1.0 as if its going to be soon(tm), I might keep just waiting for that as an option before nuking my 3.1.0 setup....

RickKukiela avatar Jun 22 '22 16:06 RickKukiela

We are also waiting for this feature, to generate classes from components if there is no API (e. g. publish Kafka Event Objects as Open Api Spec). I hope there will be soon a new release for that.

slPerryRhodan avatar Jun 23 '22 11:06 slPerryRhodan

Any updates on 3.1 support?

tobq avatar Jul 06 '22 13:07 tobq

This is a huge impediment. I too have an API that relies on 3.1 features. It seems to be taking the toolchain a very long time to support it.

Stokestack avatar Jul 15 '22 00:07 Stokestack

This is a big oof on my part. I just spent a ton of time setting up an API spec for a client and used 3.1.0 and now that its all approved I need to actually program the API server and need to generate the base files from the spec. Now I find out that not only does this package not support 3.1.0 currently but I cannot seem to find any code generator that does :( big yikes! I have to figure out what my options are at this point as my spec currently makes heavy use of the type as an array not a string and I also use oneOf with "null" or a $ref throughout the whole thing which makes it a major problem to downgrade to 3.0.3 at this point.

I see that as of 27 days ago at the time of me writing this, the 3.1 spec was added to swagger-api/swagger-parser#1535 - Does anyone have any idea when there will be a beta / snapshot release that will support 3.1.0 as if its going to be soon(tm), I might keep just waiting for that as an option before nuking my 3.1.0 setup....

Type null works with 3.0.3 specs and our tool Type arrays can be converted to oneOf with each type in a different schema.

spacether avatar Jul 15 '22 23:07 spacether

Hello! As the maintainer of openapi.tools, and as somebody works with Linux Foundation helping out in OpenAPI-land, I'm reaching out to tooling vendors to track the progress towards supporting OpenAPI v3.1, to see what roadblocks there are beyond folks just generally being busy at this ridiculous time.

OpenAPI v3.1 has a bunch of great little changes, solving problems like the JSON Schema <!=> OpenAPI Schema Object divergence. It also fixes some other inconsistencies and duplicate ways of doing things. It's the best version and everyone should be using it, but we need tooling to catch up. Just in case folks didn't notice, or don't have resources to simplify the process, I'm here to give a friendly prod and send over some handy links.

Here are a few articles showing off the differences between OpenAPI v3.0 and v3.1.

  • https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
  • https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
  • https://nordicapis.com/whats-new-in-openapi-3-1-0/

Here are some example files which can make for handy pass/fail test cases:

https://github.com/Mermade/openapi3-examples/tree/master/3.1

If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:

https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

No rush, but when you're starting work on it, please update this issue so I can update openapi.tools to reflect that, and folks will have a way to subscribe for updates.

LMK if you have any questions!

philsturgeon avatar Jul 18 '22 14:07 philsturgeon

Apart from the actual lack of 3.1 support the biggest issue I have is that this project does not seem to be open about it.

The README doesn't mention it. https://openapi-generator.tech/ prominently claims

from OpenAPI 2.0/3.x documents

which led me to believe that 3.1 be fully supported.

marcelstoer avatar Aug 02 '22 15:08 marcelstoer

Probably should say 3.0.x...

RickKukiela avatar Aug 02 '22 15:08 RickKukiela

It would be helpful to see an itemized list of what is still needed to achieve v3.1 support, so that members of the community can help out. Has anyone identified those tasks?

karenetheridge avatar Aug 03 '22 00:08 karenetheridge

It would be helpful to see an itemized list of what is still needed to achieve v3.1 support, so that members of the community can help out. Has anyone identified those tasks?

I am putting together that list now and we will publish a project very soon. This is something that we all want to add to openapi-generator. It is ~30 feature additions to store the new openapi/json schema data in our java classes. Then that data needs to be used by the generators to generate code that imposes the new json schema validation + adds new openapi features.

spacether avatar Aug 03 '22 22:08 spacether

We have a project to track adding 3.1.0 support here: https://github.com/orgs/OpenAPITools/projects/4/views/1 and welcome any PRs adding these features

Generators that will have 3.1.0 support prioritized: https://github.com/OpenAPITools/openapi-generator/issues/13073

Tag for 3.1.0 issues/PRs: https://github.com/OpenAPITools/openapi-generator/issues?q=is%3Aissue+is%3Aopen+label%3A%22Feature%3A+OAS+3.1.0+spec+support%22

spacether avatar Aug 04 '22 14:08 spacether

Can we have a way to just treat v3.1 specs as v3.0? That way we could continue to use the generator with v3.1 APIs. Today we're blocked.

alexec avatar Nov 18 '22 20:11 alexec

@alexec to do that one might need to preprocess the spec down to 3.0.3 If a 3.1.0 spec is parsed, it handles parsing differently and moves all type info into types.

spacether avatar Nov 18 '22 20:11 spacether

Thank you for fast reply:

components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: string
          example: abc123
        createdDate:
          type: string
          format: date-time
          example: 2023-01-01T00:00:00.000Z
        lastModifiedDate:
          type: string
          format: date-time
          example: 2023-01-01T00:00:00.000Z
        userName:
          type: string
          example: whoami
        content:
          type: string
          example: Hello APIs!

It creates this Java, but that's obviously wrong because the fields are Object when they should be String:

public class Document {

  @JsonProperty("id")
  private Object id = null;

  @JsonProperty("createdDate")
  private Object createdDate = null;

  @JsonProperty("lastModifiedDate")
  private Object lastModifiedDate = null;

  @JsonProperty("userName")
  private Object userName = null;

  @JsonProperty("content")
  private Object content = null;
}

alexec avatar Nov 18 '22 20:11 alexec

Right, like I said, the parser stores type info differently depending upon if the spec is 3.1.0 vs 3.0.3 or less

spacether avatar Nov 18 '22 21:11 spacether

Thank you for fast reply:

components:
  schemas:
    Document:
      type: object
      properties:
        id:
          type: string
          example: abc123
        createdDate:
          type: string
          format: date-time
          example: 2023-01-01T00:00:00.000Z
        lastModifiedDate:
          type: string
          format: date-time
          example: 2023-01-01T00:00:00.000Z
        userName:
          type: string
          example: whoami
        content:
          type: string
          example: Hello APIs!

It creates this Java, but that's obviously wrong because the fields are Object when they should be String:

public class Document {

  @JsonProperty("id")
  private Object id = null;

  @JsonProperty("createdDate")
  private Object createdDate = null;

  @JsonProperty("lastModifiedDate")
  private Object lastModifiedDate = null;

  @JsonProperty("userName")
  private Object userName = null;

  @JsonProperty("content")
  private Object content = null;
}

Were you able to resolve the issue @alexec ? For me, its generating it as follows when slotTypeId is a string: private JsonNullable<Object> slotTypeId = JsonNullable.undefined();

pratik3558 avatar Jan 06 '23 21:01 pratik3558

Hi, I tried to add the support for JsonSchema and field "types" in the PR https://github.com/OpenAPITools/openapi-generator/pull/14629, can you try the PR to check if it works on your project usign OpenAPI 3.1?

GuillaumeSmaha avatar Feb 08 '23 23:02 GuillaumeSmaha

For your info this type storage could all be way simpler long term. In my new version of this project, openapi-json-schema-generator, types are defined here I removed all the isString/isArray/isMap/isNumber/isInteger/isNull... etc properties and instead use:

    // 3.1.0
    public LinkedHashSet<String> types;
   ...

And types are set in one place for all schemas with: property.types = getTypes(p);

which works for models and properties. And to use it in templates, one can iterate over types like so in handlebars

{{#each types}}
{{/each}}

Or one can check if types contains a value:

{{#contains types "string"}}
{{/contains}}

or check if any type is allowed (type is unset)

{{#eq types null}}
{{/eq}}

or check if there is more than one type

{{#gt types.size 1}}
{{/gt}}

These updates landed in my 2.0.0 release on April 25, 2023

spacether avatar Feb 08 '23 23:02 spacether

// 3.1.0 public LinkedHashSet<String> types; public CodegenSchema contains; public LinkedHashMap<String, List<String>> dependentRequired; public boolean isBooleanSchemaTrue; // supports boolean schemas public boolean isBooleanSchemaFalse; // supports boolean schemas

Oh, this is a better idea and it seems easier ! I will check your repo :)

GuillaumeSmaha avatar Feb 09 '23 09:02 GuillaumeSmaha

Hello Is there a plan to add support for OpenAPI 3.1 in the 7.0.0 release?

adampoplawski avatar May 02 '23 08:05 adampoplawski

Any sort of updated timeline anywhere? More and more upstream projects are supporting OpenAPI 3.1. For example, FastAPI (Python project) released 0.100.0 a couple of weeks ago that targets OpenAPI 3.1 only.

I see this project at https://github.com/orgs/OpenAPITools/projects/4, but seems like very little activity in the last year. And @spacether, what's your plan with your fork? I can't quite tell how complete the OpenAPI 3.1 support is - the README still seems to indicate OpenAPI 3.0.x only. And it seems like your fork is python generator-focused.

phillipuniverse avatar Jul 24 '23 14:07 phillipuniverse

Some updates on my fork, openapi-json-schema-generator

The openapi-core team required the removal of my python generator from this repo despite it thoroughly providing openapi and json schema features, so I will no longer be contributing to this repo

If you are interested in using these features and they do not yet exist in the tooling, please write a PR in openapi-json-schema-generator

If you want json schema support in python or any other language please give the project a look and help me build it. PRs and new generators in any language are welcome We can all be the change that we want to see 🙂 I am actively working on adding 3.1.0 spec features here

spacether avatar Jul 25 '23 16:07 spacether

@spacether thanks for the extra information. Really unfortunate that some of the drama caused the fork! Your contributions speak for themselves! Seems like there is no other hope for OpenAPI 3.1 support landing in this repo 😢

in my v3 branch full statically check typing has been added to the python code which means that this generator could be ported into other static languages like Kotlin, Java, Go etc

Nice, maybe we could use the list at https://github.com/OpenAPITools/openapi-generator/issues/13073 for the next ones to prioritize. From this list, looks like it would be Java and typescript-axios.

phillipuniverse avatar Jul 26 '23 03:07 phillipuniverse