Swagger generation

[Nathan Spears]

Hello,

I've been working with Scalatra's Swagger support for a couple weeks and I have some questions I hope you guys can help me with.

I'm investigating an upgrade from Scalatra 2.5.1 to 2.6.3. There was a custom ResourcesApp.renderSwagger2 overriding the default, and I'm looking at the differences in output between 2.6.3 default swagger.json and the custom output.

1. Is the intent of the SwaggerBase.renderSwagger2 that it should be a complete solution? Or is it intended as a starting point for people to override and generate json more suited to their needs?
2. Assuming for the moment that it should be a complete solution, why is there a hardcoded 200 response field? If I want to put a description on a 200 response, I create a ResponseMessage for that but then two '200's get generated, which breaks Swagger UI (and silently!).
3. What is the preferred convention for the Type of an Operation that doesn't return anything? Void? Unit? Something else? When I left the type off, the generated swagger referred to a generated type "#/definitions/Nothing$". Putting "Void" for the type worked better, but created an empty Void definition. "Unit" seems to work best for me so far.
4. In the Swagger UI, when I edited yaml to create the API I wanted, and did an export to Scalatra, it loses information. ResponseMessages aren't there, for example. I was hoping to use this to see what "proper" Scalatra looked like for the yaml I generated. Is this Scalatra export considered, again, a starting point? Or is there an expectation that you would be able to use Scalatra to generate swagger.json, and then use the Swagger UI to export Scalatra that would generate the same json?
5. An example Scalatra app that has lots of Swagger examples for different use cases would be tremendously helpful, and I couldn't really find one. Do you guys have any go-tos for examples?

Thanks,

Nate

[Nathan Spears]

Are these questions not answerable or not interesting?

[Naoki Takezoe]

Hi Nathan.

Sorry for my very slow response.

> I've been working with Scalatra's Swagger support for a couple weeks and I have some questions I hope you guys can help me with.
>
> I'm investigating an upgrade from Scalatra 2.5.1 to 2.6.3. There was a custom ResourcesApp.renderSwagger2 overriding the default, and I'm looking at the differences in output between 2.6.3 default swagger.json and the custom output.
>
> Is the intent of the SwaggerBase.renderSwagger2 that it should be a complete solution? Or is it intended as a starting point for people to override and generate json more suited to their needs?

Basically, no. It's intended to be a complete solution.

> Assuming for the moment that it should be a complete solution, why is there a hardcoded 200 response field? If I want to put a description on a 200 response, I create a ResponseMessage for that but then two '200's get generated, which breaks Swagger UI (and silently!).

While it's intended to be a convinient default, duplicated 200
generation in explained situation should be fixed.

> What is the preferred convention for the Type of an Operation that doesn't return anything? Void? Unit? Something else? When I left the type off, the generated swagger referred to a generated type "#/definitions/Nothing$". Putting "Void" for the type worked better, but created an empty Void definition. "Unit" seems to work best for me so far.

Unit is the best solution here. Void is for representing Java's void
in Scala. It's not common in Scala. On the other hand, generating
"#/definitions/Nothing$" is not good. It might have to be treated as
same as Unit.

> In the Swagger UI, when I edited yaml to create the API I wanted, and did an export to Scalatra, it loses information. ResponseMessages aren't there, for example. I was hoping to use this to see what "proper" Scalatra looked like for the yaml I generated. Is this Scalatra export considered, again, a starting point? Or is there an expectation that you would be able to use Scalatra to generate swagger.json, and then use the Swagger UI to export Scalatra that would generate the same json?

How did you export an edited yaml to Scalatra? Scalatra's Swagger
support generates swagger.json, and its purpose is just to make
possible to just explore APIs using external tools like Swagger UI.

> An example Scalatra app that has lots of Swagger examples for different use cases would be tremendously helpful, and I couldn't really find one. Do you guys have any go-tos for examples?

I also think such examples are very helpful, but they don't exist so
far. There are only few examples in scalatra-website-examples
repository:
https://github.com/scalatra/scalatra-website-examples/tree/master/2.6/swagger-example

Anyway, I think some specific problems came out here should be filed
as issues on GitHub.

--
Naoki Takezoe