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

Open
kamaydeo opened this Issue Mar 18, 2016 · 30 comments

Comments

Projects
None yet
@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

This comment has been minimized.

Show comment
Hide comment
@wilkinsona

wilkinsona Mar 21, 2016

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@eruiz

eruiz 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.

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

This comment has been minimized.

Show comment
Hide comment
@firefoxNX

firefoxNX commented May 4, 2016

👍
+1

@wilkinsona wilkinsona changed the title from Build swagger2 specs to Build Swagger 2 / OpenAPI specs May 5, 2016

@horzsolt

This comment has been minimized.

Show comment
Hide comment
@horzsolt

horzsolt May 18, 2017

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

horzsolt commented May 18, 2017

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

@wilkinsona

This comment has been minimized.

Show comment
Hide comment
@wilkinsona

wilkinsona May 18, 2017

Member

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

Member

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

This comment has been minimized.

Show comment
Hide comment
@dlyash

dlyash 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.

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

This comment has been minimized.

Show comment
Hide comment
@krydab

krydab 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.

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

This comment has been minimized.

Show comment
Hide comment
@reda-alaoui

reda-alaoui 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?

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

This comment has been minimized.

Show comment
Hide comment
@wilkinsona

wilkinsona Aug 29, 2017

Member

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

Member

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

This comment has been minimized.

Show comment
Hide comment
@jmpascal

jmpascal 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.

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

This comment has been minimized.

Show comment
Hide comment
@wilkinsona

wilkinsona Nov 3, 2017

Member

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

Member

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

This comment has been minimized.

Show comment
Hide comment
@marceloverdijk

marceloverdijk Dec 29, 2017

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@fbenz

fbenz Jan 21, 2018

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@jwedel

jwedel 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.

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

This comment has been minimized.

Show comment
Hide comment
@lucky72o

lucky72o 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..

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

This comment has been minimized.

Show comment
Hide comment
@kamaydeo

kamaydeo 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

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

This comment has been minimized.

Show comment
Hide comment
@pax95

pax95 Aug 22, 2018

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@mduesterhoeft

mduesterhoeft Aug 26, 2018

Contributor

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.

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@klieber

klieber 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.

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

This comment has been minimized.

Show comment
Hide comment
@mduesterhoeft

mduesterhoeft Aug 29, 2018

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@jwedel

jwedel 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 👍

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

This comment has been minimized.

Show comment
Hide comment
@klieber

klieber 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.

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

This comment has been minimized.

Show comment
Hide comment
@mduesterhoeft

mduesterhoeft Aug 29, 2018

Contributor

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

Contributor

mduesterhoeft commented Aug 29, 2018

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

@melissapalmer

This comment has been minimized.

Show comment
Hide comment
@melissapalmer

melissapalmer Aug 29, 2018

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

melissapalmer commented Aug 29, 2018

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

@mduesterhoeft

This comment has been minimized.

Show comment
Hide comment
@mduesterhoeft

mduesterhoeft Aug 29, 2018

Contributor

@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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@alejandro-martin

alejandro-martin 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?

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

This comment has been minimized.

Show comment
Hide comment
@klieber

klieber 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

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

This comment has been minimized.

Show comment
Hide comment
@jaseb

jaseb 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.

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

This comment has been minimized.

Show comment
Hide comment
@wilkinsona

wilkinsona Sep 12, 2018

Member

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.

Member

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

This comment has been minimized.

Show comment
Hide comment
@klieber

klieber 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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment