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.

[fbenz]

It is possible to create a Swagger JSON file and thus a Swagger playground out of the cURL snippets generated by Spring REST Docs. I have put together instructions on how to do so: https://github.com/fbenz/restdocs-to-swagger. Two conversions (REST Docs to Insomnia and Insomnia to Swagger) are required at the moment, but it works and can be automated.

I understand the concerns about the Swagger playground. We are using Spring REST Docs to generate the documentation and in addition maintain Postman collections for ourselves and users of the API. I personally do not miss Swagger if I have the requests in Postman, but some people do prefer Swagger. A Swagger UI can be hosted alongside the API and thus one can get the documentation and a playground served with the API.

[jwedel]

It would be great to have such a thing. Our company just decided that OpenAPI is our standard for REST documentation. My team and I would rather keep on using the test driven approach with a good written documentation like REST docs generates.
Despite the fact, that we are kind of forced to use OpenAPI, I have to admit that I like the playground feature as well.

[lucky72o]

Hi! Any update on this?
Our company is moving towards OpenApi and we are forced to use swagger. I would prefer to continue use rest docs, and it would be great if rest docs will start support openApi..

[kamaydeo]

Andy,

I was an early adopter of RestDocs. I liked the concept of test driven approach that generates documentation and validates changes made to the APIs. However, OpenAPI specification is really the de facto standard for API documentation.

As I mentioned in my first post, I wish you had given a serious thought to that. I know that you had your reasons and I get that. I don't necessarily agree with it though. Anyways, it is unfortunate that there is no traction on this even after 2 years. I have already moved on from restdocs for a while now to OpenAPI specs. It's a great move for us and is working out very well as there is significant amount of tooling around it such as SwaggerEditor, API Playground etc. I know that there are several colleagues/companies have taken the same approach and have been successful with it.

I strongly urge you to give it another thought and time is an essence here. All we need is the ability to generate OpenAPI spec 2.0/3.0 output from the tests. This way you get the best of both worlds.

Thanks.
Ketan

[pax95]

@kamaydeo Couldn't agree more.
I love RestDocs and have used it the last 2-3 years, but OpenApi is the way to go. It would be awesome if RestDocs would support the OpenApi spec out of the box.

[mduesterhoeft]

We came up with a restdocs extension that adds OpenAPI support. Currently we only support the 2.0 version of OpenAPI. Especially because the tool ecosystem of OpenAPI/Swagger seems to move to 3.0 rather slowly. But supporting 3.0 possible and might be added if there is demand.

Please see https://github.com/ePages-de/restdocs-openapi.

The project comes with a custom snippet and a gradle plugin to build an OpenAPI specification as a result of your tests.

There is also a sample project.

We use the project already internally and like the results so far. Let me know what you think.

[klieber]

@mduesterhoeft nice work! Oddly enough we just started work on a very similar solution at my organization last week.

https://github.com/BerkleyTechnologyServices/restdocs-openapi

Our approach is similar but no where near as complete as what you built at this point. We did build a maven plugin instead of a gradle plugin so I'm going to take a look at porting our plugin over to consume your snippets. We hadn't gotten very far on generating snippets yet anyway so at least we could contribute the maven plugin.

I guess you can never have a unique idea in our world.

[mduesterhoeft]

@klieber - interesting - what do you think - is our version more advanced than yours?

What about moving to our restdocs-openapi and contribute a maven plugin? It would help to join forces - and it is also more fun...

[jwedel]

@mduesterhoeft @klieber That would be great, I was just about to test your extension when I realized that you used a Gradle plugin, so merging your two repo would be very helpful 👍

[klieber]

@mduesterhoeft yeah I think you've got a lot more built out than we do although most of how you did things was around the same way we were planning on doing it. Too bad we didn't see you repo last week!

I'm thinking adding the plugin to you repo might make the most sense. One thing that we were also exploring is support for generating more than just open API. If you look in our maven plugin we started to also add support for generating a postman collection. So, I'd like to continue to have that ability as well which I think should work out well.

[mduesterhoeft]

@klieber let's take the discussion here - https://gitter.im/restdocs-openapi/Lobby

[melissapalmer]

@mduesterhoeft like that idea to be able to generate more specs such as postman too

[mduesterhoeft]

@melissapalmer I aggree that it sounds tempting at first. But it also introduces a lot of complexity. We are focussed on OpenAPI at the moment. But there are ways to convert OpenAPI 2.0 into many other specifications.

We have a section in the documentation on how to convert to RAML using the oas-raml-converter - see https://github.com/ePages-de/restdocs-openapi#convert-to-raml

Also I want to mention the apimatic API transformer that allows to convert between all the popular API specification formats - also from OpenAPI 2.0 to Postman - https://apimatic.io/transformer
They also provide a REST API - https://apimatic.io/apidocs/cgaas-api/v/1_0#/http/api-endpoints/api-transformer/transform-using-file

Oh - and I forgot the easiest way - you can also just import an OpenAPI file directly into postman - https://www.getpostman.com/docs/v6/postman/collections/data_formats#importing-swagger

[alejandro-martin]

I like a lot the Spring Rest Docs approach and I understand the importance for the Open Api support.

So thanks @mduesterhoeft and @klieber for sharing your projects.

My question is, Is there will be support for a maven plugin?

[klieber]

@alejandro-martin, the maven plugin is in development right now. Hope to have it ready soon.

https://github.com/BerkleyTechnologyServices/restdocs-spec

[jaseb]

Hi all,
Been following this and also have a POC that was done for work that uses existing restdocs code, and adds swagger as a test scoped dependency for building the model.
Previously contacted @wilkinsona , but it was put aside as I moved overseas. Have tacit permission to open source the code, and will try to get it sorted asap.

[wilkinsona]

Hi, @jaseb. And I still have your email in my inbox waiting for me to get enough time to review the PoC. If you're in a position to open source, that'd be great and a PR here would be welcome so that everyone can take a look.

[klieber]

The maven plugin should be ready to go now. Still an early version though so please provide any feedback if you are running into issues. Just please leave the feedback in my projects issues list rather than adding it here.

It's still not in Maven Central so you will need to add the JitPack repositories for now.

I've also created a sample project that demonstrates using Spring REST Docs, restdocs-openapi, and restdocs-spec-maven-plugin together to create both HTML documentation and the OpenAPI 2.0 spec file at the same time.

You can find that sample project here: https://github.com/BerkleyTechnologyServices/restdocs-spec-example

[mduesterhoeft]

We renamed restdocs-openapi to restdocs-api-spec and are planning to add RAML and Postman support soon

[mduesterhoeft]

@mduesterhoeft like that idea to be able to generate more specs such as postman too

🎉 @melissapalmer with version 0.8.0 restdocs-api-spec now supports postman collections. Give it a try and let me know what you think.

https://github.com/ePages-de/restdocs-api-spec

[opticyclic]

Azure API Management takes OpenAPI as an input.

If we use Spring REST Docs we have to manually create everything in Azure which is a pain.

[jlstrater]

Since there is now an extension that provides this functionality, should we close this issue?

[wilkinsona]

Yep, I think we should. There are no plans or bandwidth to add OpenAPI support at the moment and, to my knowledge, the API spec extension is doing an excellent job of fulfilling the requirement. It also does more than this issue proposes, supporting Open API 2 and 3 as well as Postman Collections.

The API spec extension is already listed in the README so I'm going to close this issue, for now at least. If plans change and there's a compelling need for Open API support in REST Docs itself, we can re-open this issue.

[wilkinsona]

Superseded by #546.

[sdeleuze]

@wilkinsona Do you think we could add a link to the API spec extension in the reference documentation to make it more discoverable ?

[wilkinsona]

Do you have a suggestion for where it might go? I don't want to duplicate the list of third-party extensions from the README in the reference docs, and I'm reluctant to add something more detailed without also including a discussion about Swagger/OpenAPI's pros and cons which doesn't feel quite like reference doc material to me.

[sdeleuze]

I understand, the current list in the README is probably enough then.

[christophs78]

@wilkinsona: In my opinion the current status is unsatisfying. OpenAPI seems to be the "one" standard for REST-"contracts". We may like this or not. But it´s realy wide-spread. I had to evaluate https://www.uipath.com/ (RPM-solution) in the last weeks. And even this software supports the import of WSDL-Files for SOAP-based webservices and openapi.yaml for REST-based webservices.

Due to the lack of official OpenAPI-support within Spring there are multiple solutions:

• https://github.com/springfox/springfox (wide-spread; but lacks of OpenAPI 3.0 - support. The project run into major maintainance-issues over the last year.)
• https://github.com/springdoc/springdoc-openapi (a new project which was created because of the issues with springfox)
• https://github.com/ePages-de/restdocs-api-spec built on top of Spring REST Docs, as you mentioned.
• Probably a list of inhouse-solutions

It´s not clear which project we should trust. Which of this projects gets maintained a few years into the future. There may be OpenAPI 4.0 at some point in the future. Which of this projects is still alive when this arrives?

[wilkinsona]

Which of this projects gets maintained a few years into the future. There may be OpenAPI 4.0 at some point in the future. Which of this projects is still alive when this arrives?

Your first three bullets are all open source software so whether or not they are still alive when a theoretical OpenAPI 4.0 arrives is within your control. I would recommend assessing the options, trusting and using the one that best meets your current needs, and becoming an active member of its community to help it to grow and evolve. Given that you appear to be coming at this from a REST Docs angle, I personally would consider https://github.com/ePages-de/restdocs-api-spec first.

[christophs78]

Yep. That´s what i do currently. :-) Originally thought Springfox is the way to go. Cloned the project... After reading deeper into this topic i have to think one more time about the options.