Are this project dead?

[yeryomenkom]

What is current version of this project? When will be added new version of scala-swagger-plugin?

[andrendp]

Can we start getting some movement again. When can we kick start this again.

[JFCote]

Hi guys, I will give you my 2 cents. I'm the main contributor to the Java Play Framework swagger-codegen. If you never used swagger-codegen ( https://github.com/swagger-api/swagger-codegen ), it takes a swagger spec (yaml or json) and generate a server (or client, as you wish). With some parameters during the generation, you can chose how you want your server to be generated and which file you want to overwrite or not.

There is also a parameter to have the swagger-ui included in the generation and available at a url like localhost:9000/api .

This generator is very new and available in the master of the project. I'm not sure if it's available in any release so far but it will soon be.

My advice to anyone using the very buggy swagger-play and Java (Scala generator not available) would be to switch to swagger-codegen instead. The project has never been more alive and I will try to fix any bug found by the community as soon as I can. There is also a lot of other contributors to swagger-codegen that help me in this task.

Hope that helps! Thanks!

[laguiz]

@JFCote Not sure what you mean with replacing swagger-play with swagger-codegen.

Based on my understanding they are not doing the same. I understand that swagger-play take your source code and it generate a spec in json format as output while swagger-codegen take json file as input and generate client, stub, html, etc.

Did I miss something with swagger-codegen. Could we generate json from source code ? Maybe you think it's a bad practice and it's would be better to use editor or create the file manually ?

[JFCote]

Hi @laguiz ,

Your understanding is right. In fact, there is 2 flows depending on your source of truth (SOT). The good practice is to have a YAML file as a SOT instead of the code with annotation. There are a lot of advantages with this. You can start designing your API without thinking of the code. Even not-so-technical people can write yaml and discribe their needs in the API before even having the code to test it. You have a documentation available in real time when documenting it.

Add to this that you can generate stuff (server, client, json, html, etc..) with swagger-codegen and you have what I think is a perfect solution. Let's say your front-end is using javascript but there is a new project that needs your api in typescript with angular2? Well, one command line later you have a complete typescript-angular2 client ready to use that you can give to the front-end theme at no extra effort!

When using the flow where the SOT is the code with annotations that generate a spec, the only thing you have is a spec. It is generated "after the fact" and it's only available to the developers to modify it.

It's your choice at the end what flow you want to follow depending on the scenario and needs of your project. I was just proposing a solution for all the people realizing that swagger-play is mostly abandoned and full of bugs.

I understand that people with an already existing API with thousands of endpoint don't really want to move to swagger-codegen but if you are just starting, then I would highly suggest that you look at swagger-codegen!

Have a good day!

[laguiz]

@JFCote Thank for your feedback. Looks like putting the SOT on the yaml file is a better choice. I will give a try to see how it goes. Thank you.

[laguiz]

@JFCote I'm currently documenting my API using yaml. So far it's not that bad. Big advantage I see is that it's easy to make a clear distinction between what you describe and how you implement (especially if you need to manage multiple versions). Risk is to desynchronize your doc with your implementation.

I manually implement the code without using swagger-codegen. As you mentioned we could use swagger-codegen to "bootstrap server code" but it's not clear yet how the dev loop cycle works (eg. edit yaml -> generate server code skeleton -> edit yaml -> generate server code skeleton -> ...). For now manual implementation seems to be OK for me as we will force ourself to first touch yaml file before anything else.

Editing yaml file manually is not that a big deal and force me to think about any breaking changes I could introduce when I go to the implementation after defining the "what" in yaml.

For others that would go creating yaml files manually and want a quick nice UI I use the simple to use https://github.com/swagger-api/swagger-ui to show a nice UI to my users. I simply copy paste /dist folder in my project and use the query string parameter ?url=http://urltomyswaggersepc/v1.yaml to load the spec I want.

I will communicate with my users about swagger-codegen to let them generate clients if they want.

Thank you again @JFCote for your valuable feedback.

[JFCote]

@laguiz : Thanks for the feedback.

About the dev loop cycle, I use mainly basic powershell script to choose what I want to copy. I generate everything and pick and choose what I want to copy over my real ongoing project. For example, I always copy the controller and the interface but only copy the implementor if it's not already existing, preventing my business logic to be overwriten. You can also choose to put "swagger-codegen-ignore" file when generating, preventing some files to be generated. (Works like git-ignore).

Also, there is also an option in the JavaPlayFramework generator that is true by default that generates the doc. So there is no risk that your doc is not in sync with the implementation. You just need to go to http://localhost:9000/api you will get the latest doc based on the spec.

I highly suggest, if you choose to write the yaml, to use swagger-codegen since everything will be in sync!

Thanks for the feedback and happy coding!

[laguiz]

@JFCote I definitely like what i see here : https://github.com/swagger-api/swagger-codegen/tree/master/samples/server/petstore/java-play-framework including fetch swagger-ui from webjars, creation of wrapper controller and interfaces, routes, usage of bean validation, ApiCall/ApiAction.

I will give it a try :)

Not related to swagger-codegen but I'm now thinking how to properly handle versioning. In the demo I see "v2" mentioned on the router pointing to "non versioned" implementation (eg. no version referenced in java packages). Looks good to me. In case we have a "v3" we could then append new routes that would point to existing implementation if no changes. If we have new things it's easy too.

Hard thing happen if we have some kind of breaking changes on an operation. Would you start introducing version in package names to fork the interface/implementaion between "v2" and "v3" ?

You will probably say that it depends :). In case we have a new optional parameter I would go to change the existing JAVA Interface and implementation to handle this new parameter. In that case "v2" will still work because the parameter is optional. Advantage is that we only have 1 code base that support both versions. Difficulties would come if we have a breaking change like "add required parameter". In that case I'm not sure if it's best to fork, change method name, or something else.

Same ideas apply if for example we return a list of Pet and want to add or remove a property in the Pet object.

I think we should always try to make interfaces and implementations backward compatible then we should not think of forking implementations but I'm not sure it would always be possible (I have not much experience on this expect applying the rule of "make it backward compatible for some times").

In my current project it's not a big deal because I have direct contact to the api consumers but you know...

If you have any experience in this, feel free to share :)

Original topic is Are this project dead? so... We are probably out of the topic here. I was just writing my thoughts.

Regards!

[JFCote]

Hi @laguiz . That's a big subject and I don't have a lot of experience since we are just starting our API where I work but there is multiple way to deal with version in swagger. There is the version number of the spec itself, there is the "basepath" that you can use to change all your path at once. And you can also just add the version to the path itself.

As for the model, I'm not sure what is the best practice but you can look at how they do it in swaggerhub. Sorry I can't help you more and like you said, we are probably off topic but I'm pretty sure it can help others choose between swagger-play and swagger-codegen.

Have a good day!

[domdorn]

For creating sourcecode from json/yaml swagger files, you should take a look at https://github.com/ebowman/api-first-hand imho, this one is far more advanced. @JFCote you might be better off to create a java-adapter in that project than creating your own codegen that in the end has to solve all the same problems the api-first project already solved (e.g. what to do with own code when the spec changes/gets an update, etc.)

[JFCote]

@domdorn : Thanks for the suggestion, I didn't know this project. My team and I have choose the swagger-codegen project because it can creates any client and any server in minutes. We are not sure we will use Play Framework forever for our backend. In fact, long compilation time and many other bugs from Play Framework continue to haunt us version after version.

With swagger-codegen, we are not tied to a technology. We have our source of truth and can switch to .NET core when we are ready or something like that. Since the "business logic" is all in the same file, there is only that part that need to be converted. Same thing goes for the client. Right now we have typescript without any framework so we use the Typescript-JQuery client generated from the same spec. Later, when we will move to Angular 4 or any other frontend framework, we will just generate the client and keep going.

As for the problem of the business logic, it's a very simple one to fix. Either use swagger-codegen-ignore file (works like git-ignore) so that you don't generate stuff you don't want to override. Or, like I did, you always generate everything in a temp folder and craft a small .bat/ps1/.sh file that copy the files you need over the destination.

In the end, I think it's a matter of choice and what the project is using. Have a good day!