Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build Swagger 2 / OpenAPI specs #213

Closed
kamaydeo opened this issue Mar 18, 2016 · 42 comments
Closed

Build Swagger 2 / OpenAPI specs #213

kamaydeo opened this issue Mar 18, 2016 · 42 comments

Comments

@kamaydeo
Copy link

@kamaydeo kamaydeo commented Mar 18, 2016

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
Copy link
Member

@wilkinsona wilkinsona commented Mar 21, 2016

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
Copy link

@eruiz eruiz commented May 4, 2016

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
Copy link

@firefoxNX firefoxNX commented May 4, 2016

👍
+1

@wilkinsona wilkinsona changed the title Build swagger2 specs Build Swagger 2 / OpenAPI specs May 5, 2016
@horzsolt
Copy link

@horzsolt horzsolt commented May 18, 2017

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

@wilkinsona
Copy link
Member

@wilkinsona wilkinsona commented May 18, 2017

@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
Copy link

@dlyash dlyash commented Jun 6, 2017

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
Copy link

@krydab krydab commented Jul 27, 2017

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
Copy link

@reda-alaoui reda-alaoui commented Aug 23, 2017

Hello @wilkinsona ,

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

@wilkinsona
Copy link
Member

@wilkinsona wilkinsona commented Aug 29, 2017

@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
Copy link

@jmpascal jmpascal commented Oct 25, 2017

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
Copy link
Member

@wilkinsona wilkinsona commented Nov 3, 2017

@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
Copy link
Contributor

@marceloverdijk marceloverdijk commented Dec 29, 2017

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
Copy link
Contributor

@fbenz fbenz commented Jan 21, 2018

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
Copy link

@jwedel jwedel commented May 17, 2018

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
Copy link

@lucky72o lucky72o commented Aug 22, 2018

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
Copy link
Author

@kamaydeo kamaydeo commented Aug 22, 2018

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
Copy link
Contributor

@pax95 pax95 commented Aug 22, 2018

@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
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Aug 26, 2018

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
Copy link

@klieber klieber commented Aug 29, 2018

@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
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Aug 29, 2018

@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
Copy link

@jwedel jwedel commented Aug 29, 2018

@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
Copy link

@klieber klieber commented Aug 29, 2018

@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
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Aug 29, 2018

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

@melissapalmer
Copy link

@melissapalmer melissapalmer commented Aug 29, 2018

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

@mduesterhoeft
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Aug 29, 2018

@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
Copy link

@alejandro-martin alejandro-martin commented Sep 11, 2018

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
Copy link

@klieber klieber commented Sep 12, 2018

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

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

@jaseb
Copy link

@jaseb jaseb commented Sep 12, 2018

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
Copy link
Member

@wilkinsona wilkinsona commented Sep 12, 2018

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
Copy link

@klieber klieber commented Sep 15, 2018

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
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Oct 31, 2018

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

@mduesterhoeft
Copy link
Contributor

@mduesterhoeft mduesterhoeft commented Jan 12, 2019

@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
Copy link

@opticyclic opticyclic commented Jun 2, 2019

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
Copy link
Contributor

@jlstrater jlstrater commented Jun 3, 2019

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

@wilkinsona
Copy link
Member

@wilkinsona wilkinsona commented Jun 3, 2019

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 wilkinsona closed this Jun 3, 2019
@wilkinsona
Copy link
Member

@wilkinsona wilkinsona commented Jun 3, 2019

Superseded by #546.

@sdeleuze
Copy link

@sdeleuze sdeleuze commented Jun 3, 2019

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

@wilkinsona
Copy link
Member

@wilkinsona wilkinsona commented Jun 3, 2019

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
Copy link

@sdeleuze sdeleuze commented Jun 3, 2019

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

@christophs78
Copy link

@christophs78 christophs78 commented Aug 23, 2019

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

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
Copy link
Member

@wilkinsona wilkinsona commented Aug 23, 2019

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
Copy link

@christophs78 christophs78 commented Aug 23, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can’t perform that action at this time.