New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Question: Plan for OpenAPI-Specification 3.0 #4669

Open
JLLeitschuh opened this Issue Jan 28, 2017 · 38 comments

Comments

Projects
None yet
@JLLeitschuh
Copy link
Contributor

JLLeitschuh commented Jan 28, 2017

With the first Implementer Draft of the 3.0 spec due to be released at the end of February is there a plan to begin implementing the features of the 3.0 spec into the generator?

https://www.openapis.org/blog/2017/01/24/a-new-year-a-new-specification

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented Jan 28, 2017

We're getting there...

@akawalsky

This comment has been minimized.

Copy link

akawalsky commented Mar 1, 2017

With today's release of the new spec 3.0, is there any update on this?

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented Mar 1, 2017

It is under way :)

@wing328 wing328 added this to the Future milestone Mar 2, 2017

@nahumclements

This comment has been minimized.

Copy link

nahumclements commented May 11, 2017

Do we have any idea of which release support for the 3.0 spec might come in?

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented May 11, 2017

There will be a 3.0.0 branch, followed up by a 3.0 release of the codegen.

@nahumclements

This comment has been minimized.

Copy link

nahumclements commented May 12, 2017

Great, thanks. Is there any update on roughly when that might be coming?

@slinkydeveloper

This comment has been minimized.

Copy link

slinkydeveloper commented Jul 12, 2017

+1

@mjbryant

This comment has been minimized.

Copy link

mjbryant commented Jul 26, 2017

Any update on when 3.0.0 might be released?

@wing328

This comment has been minimized.

Copy link
Contributor

wing328 commented Jul 30, 2017

@mjbryant we've not yet set any release date for v3.0.0. Swagger Parser needs to be updated first to support OAS 3.0.

Next Swagger Codegen release is v2.3.0 (with many breaking changes) by the end of Aug.

@yanniks

This comment has been minimized.

Copy link

yanniks commented Aug 5, 2017

Is there any possibility to build the Codegen with the experimental branch for Swagger Parser?
Since the Spec 2.0 is no longer online, it's hard for us to work with Swagger right now.

@fehguy

This comment has been minimized.

Copy link
Contributor

fehguy commented Aug 5, 2017

What do you meant the 2.0 spec is no longer online?

The 3.0 support is in progress but will take some time.

@yanniks

This comment has been minimized.

Copy link

yanniks commented Aug 7, 2017

I'm sorry, I was wrong with my previous comment. What I actually ment is that if people get to the Swagger website and go to the "Specification" page, they will only get the 3.0.0 spec. That intents that this is the current release (which is right) and that this is the release they can fully work with (which is wrong).
Additionally, the spec 2.0 is pretty well hidden.

@vthornheart-bng

This comment has been minimized.

Copy link

vthornheart-bng commented Aug 16, 2017

Indeed, I just happened to run into what @yanniks mentioned a few days ago. I just wrote an API generator for our project, and used the specs I could find: which, on the Swagger site, is OpenAPI 3.0. This means I'll have to use the snapshot build of swagger-codegen 3.0.0: which I don't mind as long as it works, but it did take me by surprise that the spec pointed to by Swagger's site wasn't the same one supported by the tools.

No biggie in my case, I'll just use the snapshot.

Anything I can do to help codegen 3.0 along? Embarrassingly, I've never actually contributed to an open source project before. But I'd be glad to help here as time allows if I can be of assistance! Is there a task list somewhere of features that need to be re-implemented or changed to get 3.0 out the door? (I see a filter for 3.0.0 in milestones, but there's nothing under it)

@wing328

This comment has been minimized.

Copy link
Contributor

wing328 commented Aug 17, 2017

@vthornheart-bng

This comment has been minimized.

Copy link

vthornheart-bng commented Aug 17, 2017

@wing328 Ah, can do! I'll get things set up and give it a run through our new spec file tonight.

@vthornheart-bng

This comment has been minimized.

Copy link

vthornheart-bng commented Aug 17, 2017

Okay, so good news and bad news. Good news is that my pretty darn complex spec did indeed parse, after some ado trying to get Maven to download the dependencies correctly. (I haven't done Java development in... jeez, 15 years or so now. This dependency tooling is fascinating and useful, but definitely seems to require some odd manual work to get going! But I digress!)

Anyways, the test I did was super simple, but I'll do more significant testing shortly. It was able to pass the "testSimple" tests of just making sure it gets a result at all and that the openAPI Version property was there.

What didn't work was running swagger-codegen-3.0.0 against it. Looking in the code, I could be mistaken but I think swagger-codegen-3.0.0 is still pointing at the 2.x compatible SwaggerParser. It ends up silently barfing on my 3.0.0 spec file, and then throwing an error because there was no input (in fact, the input wasn't parsed correctly and thus it appears to have been ignored).

Is my investigation correct? Is there perhaps a newer build of swagger-codegen-3.0.0 than what's in the 3.0.0 branch that might be closer to working? Or should I alter my spec generator to generate 2.x specs for the time being?

@vthornheart-bng

This comment has been minimized.

Copy link

vthornheart-bng commented Aug 17, 2017

Also, I did run into something interesting when trying to build swagger-codegen-3.0.0 from source after I went digging for the reason why it said "input or config not found". Maven choked trying to grab:

http://github.com/swagger-api/swagger-ui/archive/master.tar.gz

I could reach it just fine via browser, so I ended up downloading it, changing my hosts file so I was impersonating github.com, and hosting it in the same path. At that point, it worked. But it was a pretty odd situation!

@no-logic

This comment has been minimized.

Copy link

no-logic commented Sep 8, 2017

Is there a loose date estimate for supporting the 3.0 spec? The core/parser/editor are all using OAS 3.0 now, but the codegen 3.0.0 snapshot from Sept 4th still doesn't parse a yaml, let alone generate the Java server-side.

I'm about to add a ton of endpoints to our APIs, and want to take advantage of oneOf/allOf ... I don't need an exact date or anything, but if codegen support is still months away (like vt-hornheart, I'm ok with using/testing the SNAPSHOT builds), I'll have to move forward within the limitations of the 2.0 spec ... and this would mean expensive re-writes later that will probably never happen....

@CommodoreBeard

This comment has been minimized.

Copy link

CommodoreBeard commented Nov 9, 2017

Two months since the last update here, and the last codegen 3.0 SNAPSHOT was pushed on September 4th, which as @no-logic stated above is still failing to parse openapi in yaml files.

Has there been any new communication on this that I am not aware of?

@DanielJoyce

This comment has been minimized.

Copy link

DanielJoyce commented Nov 10, 2017

Yeah seems kinda half baked to push 3.0 and its barely supported by any tooling even months after its release.

@wing328

This comment has been minimized.

Copy link
Contributor

wing328 commented Nov 10, 2017

Please have a look at https://github.com/swagger-api/swagger-codegen/tree/3.0.0_enhancements

@HugoMario from SmartBear is working on that.

@robbiecooray

This comment has been minimized.

Copy link

robbiecooray commented Nov 17, 2017

Hi @HugoMario , can you please let us know the ETA on 3.0 support?

@MikeRalphson

This comment has been minimized.

Copy link
Contributor

MikeRalphson commented Nov 20, 2017

Please see #7003 for an experimental implementation of the generator engine in Node.js which supports OpenAPI 3.0

@ChristianSauer

This comment has been minimized.

Copy link

ChristianSauer commented Nov 24, 2017

We are using Python and .Net Core - so it'S not really useful.
I am severely pissed atm - your editor could at least issue a warning that that does not work atm.

@nicolasaragon

This comment has been minimized.

Copy link

nicolasaragon commented Dec 20, 2017

Great work on the OAS3 specification. I spent roughly 9 hours and I am happy with the result. The editor was helpful too. I want to keep my API and I want to keep using OAS3.

What is the planned date for OAS3 support in swagger-codegen?

This will help me choose between waiting for support, or whipping up a template and parser by myself.

Thank you!

@ghost

This comment has been minimized.

Copy link

ghost commented Jan 26, 2018

Hey guys, any updates of a promising OAS 3 Parser? Seems like everybody needs it (including me) and most of us are willing to build one but it's been a while now and there's still no "industry-standard" parser out there... at least none that I can find. It's funny how Swagger (OAS) official website is littered with OAS 3.0 terminology ('components', 'content', ect.) but editor.swagger.io raises an error if you so much as have {"swagger": "3.0"} in your doc...

@MikeRalphson

This comment has been minimized.

Copy link
Contributor

MikeRalphson commented Jan 26, 2018

but editor.swagger.io raises an error if you so much as have {"swagger": "3.0"} in your doc...

Try { "openapi": "3.0.0" }

@webron

This comment has been minimized.

Copy link
Member

webron commented Jan 26, 2018

For everyone here, in case you didn't notice we published a new version of the codegen yesterday, providing initial support for OAS3. Being a major version, there are numerous changes, not all related just to the OAS3 support. We encourage you all to read the release notes and the FAQ to see what has changed, and we're looking forward to your feedback and further contributions.

@jonschoning

This comment has been minimized.

Copy link
Contributor

jonschoning commented Jan 26, 2018

https://github.com/swagger-api/swagger-codegen/releases/tag/v3.0.0-rc0

  • OpenAPI 3.0 support.

Does OpenAPI 3.0 mean just that 2.0 specs can be converted to 3.0, or does it mean that the new features that OpenAPI 3.0 are now handled by the java generator?

The release notes don't specify how much of the new OpenAPI 3.0 features are supported.

Specifically, for example, Multiple content-types with different Schemas:
#6740

Also mentioned here:
#6077

Well 3.0 adds a lot of complexity to both requests and responses since you can use oneOf and other composition patterns. That, and the fact that you can have different schemas on each media type, means that we no longer can return a single response payload for operations under anything but hello-world-style apis.

And based on the response schema, the end-user will need to cast or coerce the response into the type that they expect (assuming a typed language).

Are the above handled in this release?

@wol190

This comment has been minimized.

Copy link

wol190 commented Jan 26, 2018

Fantastic that to see the rc0 released, great news. It would be very helpful to see a usage example, since I'm struggling so far:

$ java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -l java -i ../petstore.yaml -o C:/tmp/server/petstore3/java
[Thread-0] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[Thread-0] ERROR io.swagger.codegen.DefaultCodegen - String to be sanitized is null. Default to Object
[Thread-0] ERROR io.swagger.codegen.DefaultCodegen - String to be sanitized is null. Default to Object
Exception in thread "Thread-0" java.lang.RuntimeException: Could not generate model 'Error'
at io.swagger.codegen.DefaultGenerator.generateModels(DefaultGenerator.java:407)
at io.swagger.codegen.DefaultGenerator.generate(DefaultGenerator.java:722)
at io.swagger.codegen.cmd.Generate.run(Generate.java:312)
at java.base/java.lang.Thread.run(Unknown Source)
Caused by: java.io.FileNotFoundException: /v2/Java/\model.mustache
at com.github.jknack.handlebars.io.URLTemplateLoader.sourceAt(URLTemplateLoader.java:70)
at com.github.jknack.handlebars.Handlebars.compile(Handlebars.java:357)
at com.github.jknack.handlebars.Handlebars.compile(Handlebars.java:343)
at io.swagger.codegen.DefaultGenerator.getHandlebars(DefaultGenerator.java:1013)
at io.swagger.codegen.DefaultGenerator.processTemplateToFile(DefaultGenerator.java:738)
at io.swagger.codegen.DefaultGenerator.generateModels(DefaultGenerator.java:394)
... 3 more

The build is successful, using "mvn clean package":
[INFO] --- maven-dependency-plugin:2.8:copy (default) @ swagger-generator ---
[INFO] Configured Artifact: org.eclipse.jetty:jetty-runner:9.2.9.v20150224:jar
[INFO] Copying jetty-runner-9.2.9.v20150224.jar to C:\OpenApi\swagger-codegen-3.0.0-rc0\modules\swagger-generator\target\lib\jetty-runner.jar
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] swagger-codegen-project ............................ SUCCESS [ 1.576 s]
[INFO] swagger-codegen (core library) ..................... SUCCESS [ 31.129 s]
[INFO] swagger-codegen (executable) ....................... SUCCESS [ 15.074 s]
[INFO] swagger-codegen (maven-plugin) ..................... SUCCESS [ 11.587 s]
[INFO] swagger-generator .................................. SUCCESS [ 28.797 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:28 min
[INFO] Finished at: 2018-01-26T21:45:50Z
[INFO] Final Memory: 62M/1008M
[INFO] ------------------------------------------------------------------------

But looking at the output there are errors:

Tests run: 0, Failures: 0, Errors: 0, Skipped: 0

[INFO]
[INFO] --- maven-surefire-plugin:2.19.1:test (test-testng) @ swagger-codegen ---


T E S T S

Running TestSuite
[main] INFO org.reflections.Reflections - Reflections took 266 ms to scan 2 urls, producing 43 keys and 232 values
[main] INFO org.reflections.Reflections - Reflections took 159 ms to scan 2 urls, producing 43 keys and 232 values
[main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[main] WARN io.swagger.codegen.DefaultCodegen - generated unique operationId duplicate_0
[main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] INFO io.swagger.codegen.ignore.CodegenIgnoreProcessor - No .swagger-codegen-ignore file found.
[main] WARN io.swagger.codegen.DefaultCodegen - Empty operationId found for path: get /pet. Renamed to auto-generated operationId: petGet
[main] WARN io.swagger.codegen.ignore.CodegenIgnoreProcessor - Output directory does not exist, or is inaccessible. No file (.swagger-codegen-ignore) will be evaluated.
[main] ERROR io.swagger.codegen.languages.AbstractJavaCodegen - No Type defined for Property Pet
[main] ERROR io.swagger.codegen.DefaultCodegen - String to be sanitized is null. Default to Object
...

@webron

This comment has been minimized.

Copy link
Member

webron commented Jan 26, 2018

@jonschoning - all great questions, thanks for bringing those up.

From the FAQ:

Q: What does support for OAS3 mean?
A: API definitions of previous versions of the spec will be automatically converted to OAS3, and only then the code will be generated. Since our conversion is also in RC mode right now, we expect there to be broken conversions, and with your tickets we can have those issues resolved.

So yes, older versions would be automatically converted to OAS3.

As for multi media-type support, that's a great question for @HugoMario.

@wol190 (and everyone) - we're expecting this release to have some hiccups and missing docs. We appreciate everyone who's testing things out. For any issues found, I'd encourage you to file individual tickets, as those would be easier to track and resolve. We'd be happy to push out an rc1 release as soon as the major obstacles are cleared out.

@wol190

This comment has been minimized.

Copy link

wol190 commented Jan 27, 2018

@webron as requested, #7509 raised.

@ghost

This comment has been minimized.

Copy link

ghost commented Jan 29, 2018

Try { "openapi": "3.0.0" }

Lol, for a second I thought that would fix it, but unfortunately I still get the error message:

Schema error at swagger should be equal to one of the allowed values allowedValues: 2.0

@wol190

This comment has been minimized.

Copy link

wol190 commented Jan 29, 2018

Hi @Jonas-Bezzubovas. The following works fine for me in http://editor.swagger.io/. Hope that helps.

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
servers:
  - url: http://127.0.0.1:8080
paths:
  /pets:
    get:
      summary: Return the pet
      operationId: getThePet
      responses:
        '200':
          description: A pet
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pet"
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      example:
        id: 1
        name: "Trevor"
@ghost

This comment has been minimized.

Copy link

ghost commented Feb 1, 2018

Hey @wol190, that actually fixed it. Cheers mate

@kalexmills

This comment has been minimized.

Copy link

kalexmills commented Apr 30, 2018

@wol190: I am still seeing issues resolving model.mustache files on the current release of 3.0.0

@adrienucp

This comment has been minimized.

Copy link

adrienucp commented Jul 27, 2018

Any plans for Node.js server code generation with OAS 3.0 ?

@azraino

This comment has been minimized.

Copy link

azraino commented Nov 29, 2018

Hi Guys,

Any news regarding OAS3 and swagger codegen for Springboot?

Thank you very much.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment