Build Swagger 2 / OpenAPI specs

[kamaydeo]

I like the TDD approach to documenting your restful api. However, I love "API Playground" feature enabled by swagger specification. I wish there was a way to get best of both worlds.

Is there a way to build swagger specs from spring rest docs? may be via building custom request/response preprocessors.

Do you have any thoughts or recommendations?

[wilkinsona]

You're not the first person to look for such a feature, and I'm sure you won't be the last.

I'm rather torn on trying to add support for generating a Swagger specification. When you describe Swagger as providing an "API Playground", you've drawn a very important distinction that many others do not. I firmly believe that Swagger's UI is not a substitute for API documentation and using it as such isn't good for a service or its users.

My fear is that if Spring REST Docs provided support for producing a Swagger specification, people would then use that specification to populate Swagger's UI and consider their service to be documented. It's a matter of weighing up trusting people to do the right thing, versus encouraging people to shoot themselves in the foot.

[eruiz]

Hi Andy, as I commented in #227 what I think it is important of having the support for the OpenAPI Specification is, as said in the spec, let the "computers to discover and understand the capabilities of the service".

I think It doesn't matter if that API could be accessed with Swagger UI or not, the important thing is to have an URL from which download the specification of the REST services. I think it could be very useful to generate clients easily.

So It could be a great feature for Spring REST Docs.

[firefoxNX]

👍
+1

[horzsolt]

Hi, any updates here? Has anything happened since the last post?

[wilkinsona]

@horzsolt No updates to report at this time. The idea hasn't been rejected (hence the issue still being open) and I have given it some thought (generating a single spec from a whole suite of tests is an interesting problem) but I don't have any specific plans to tackle it at this time.

[dlyash]

Just another use case what it can be useful.

We plan to use something like http://readme.io/ to document our API. This service allows us to feed it a swagger.json, so it would be great if we could generate it using Spring REST Docs.

[krydab]

Hi All, I would like to add that currently I need to decide if I use swagger or spring rest docs in my new project. I strongly believe that you plan to implement the Open API standard in spring rest docs.

Test driven documentation is worth to go that way however ability to generate client code is awesome as well.

My feeling is that generating {open-api}.json is to be or not to be for spring rest docs.

[reda-alaoui]

Hello @wilkinsona ,

Would you accept a PR adding swagger / OpenApi specification generation?
Or haven't you decided yet to include this feature?

[wilkinsona]

@reda-alaoui I can't really say whether or not I'd accept a PR until I've seen it. I'm not fundamentally opposed to adding Swagger/OpenAPI support, but it would depend on the complexity that it introduces. It may turn out that it would be better as a third-party extension with any extra plug points being added to REST Docs to make that possible.

[jmpascal]

Aloah,

I would share a 2cts input/experience here (instead of opening a new issue) as in my project we currently investigate how to make our Public API better in general (documentation, discoverability, usage etc...)

The fact is OpenAPI spec (V3) is now a standard specification to describe a REST API. It's supported by the OpenAPI Initiative and backed by a lot of big software company. Now because those files are becoming standard description format for REST API a lot of tools/companies/projects can use this file to do different things like

• Creating an environment to design and collaborate on API
• Improving API Discoverability
• Creating static documentation or website
• Generating Client/Server implementation
• Improve API Test Automation
• Better API Monitoring
• Easier API Integration
  After all It’s the purpose of having standard! It’s a way to make everybody life easier and integrates each other more easily.

Because of that we have to generate the specification file for each of our APIs.

The fact is documentation generated by Spring Rest Docs is better & easier than Swagger V2 annotated spring project. Swagger V2 has indeed some design issues and even if you annotated all Spring RestController it wouldn’t cover all the subtle that Spring MVC / Rest Doc understand by default. That's why I understand perfectly the position from Rest Doc to not support Swagger V2.

But I might consider with Open API Spec V3 those early design issues have mostly disappeared. It's more flexible than V2 in my mind and it will become a format to share API information between system/tools/apps.

So the problem we encounter now is how from the code (as we use spring MVC of course) can we generate the spec file associated and/or API documentation associated.

As Spring & Maven user we used/tested both SpringFox & swagger-maven-plugin to generate our spec file. Previously of course we also added Swagger annotation in our code base to improve information. At the end we also use other plugins to generate static asciidoc.

But the issue at this date is neither of those plugins support the new V3 Spec and doesn't necessarily supports all Spring MVC subtles.

So here I see eventually an opportunity to (not necessary this project as I mentioned early it's a shared input/XP) create/have/extend a project that would use the spring MVC information and generate the V3 Spec file associated.

Is it going to be Spring Rest Doc extension, evolution or a new project I have no idea. But I would love to hear if my position/analysis is minor or a real idea ?

Thanks in advance.

[wilkinsona]

@jmpascal Thanks for sharing your thoughts. I'll need to read up on the V3 spec to know how far it goes to addressing my concerns. However, given that it appears that Swagger UI will support the V3 spec, I expect that my concern above that it's no substitute for API documentation won't have been addressed.

[marceloverdijk]

In our projects we are quite happy with the output of Spring REST Docs as documentation.
And of course the TDD approach is brilliant and gives us a great feeling the docs are up to date.

That being said, we also get questions from clients if we can deliver a OpenApi spec file for our api. Some want to use it in Swagger UI as they prefer that over html documentation, but other clients want to use it to generate code.

So it would be very nice that besides generating the standard REST Docs we could also generate an OpenApi spec file.

We have no intention to replace the REST Docs documentation but offering a complementary OpenApi spec could have benefits.

Currently we are experimenting with a handcrafted OpenApi spec file meaning we are documenting everything twice. Note we are using Atlassian’s https://bitbucket.org/atlassian/swagger-request-validator to validate if the spec file is missing data returned by the api.

It’s not optimal but no other way at the moment.