Swagger-codegen: Question: Plan for OpenAPI-Specification 3.0

[JLLeitschuh]

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]

We're getting there...

[akawalsky]

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

[fehguy]

It is under way :)

[nahumclements]

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

[fehguy]

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

[nahumclements]

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

[slinkydeveloper]

+1

[mjbryant]

Any update on when 3.0.0 might be released?

[wing328]

@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]

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]

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]

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]

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]

@vthornheart-bng can you help test Swagger Parser 3.0.0-rc2 (https://github.com/swagger-api/swagger-parser/tree/feature/3.0.0-rc2)?

Ref: https://github.com/swagger-api/swagger-parser/issues/417

[vthornheart-bng]

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

[vthornheart-bng]

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]

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]

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]

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]

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

[wing328]

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]

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

[MikeRalphson]

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

[ChristianSauer]

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.

[hk6an6]

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]

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]

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]

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]

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:
https://github.com/swagger-api/swagger-codegen/issues/6740

Also mentioned here:
https://github.com/swagger-api/swagger-codegen/issues/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]

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-generatortarget\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]

@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]

@webron as requested, #7509 raised.

[ghost]

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]

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]

Hey @wol190, that actually fixed it. Cheers mate

[kalexmills]

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

[adrienucp]

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

[azraino]

Hi Guys,

Any news regarding OAS3 and swagger codegen for Springboot?

Thank you very much.

[alfirin]

Hey guys,

Any news regarding OAS3 and swagger codegen for Springboot or others?

In advance, thank you very much.

[HugoMario]

hi @alfirin @azraino ,

we have added springboot 2 (experimental version) in recent releases