Open mduesterhoeft opened 6 years ago
@mduesterhoeft I should be able to add support to the restdocs-spec-maven-plugin for RAML. It would be very simple if we could remove some of the duplication between this project and restdocs-openapi. Is there really any reason why both projects need their own custom snippet? Really the snippet is just a data dump into json files that then the generators consume to create the spec definition. If we could come up with a common model for resource.json
then anyone can write a generator for any spec they wish.
In other words, have a project structure like this:
restdocs-resource-snippet - spring rest doc extension that produces resource.json
files
restdocs-resource-model - contains the classes for the ResourceModel
restdocs-raml-generator - consumes a list of ResourceModel
objects and produces a RAML spec
restdocs-openapi-generator - consumes a list of ResourceModel
objects and produces an OpenAPI spec
restdocs-raml-gradle-plugin - generates raml spec from resource.json
using the restdocs-resource-model and restdocs-raml-generator
restdocs-openapi-gradle-plugin - generates openapi spec from resource.json
using the restdocs-resource-model and restdocs-openapi-generator
restdocs-spec-maven-plugin - generates raml or openapi spec from resource.json
using restdocs-resource-model, restdocs-raml-generator, and restdocs-openapi-generator
Does that make sense? This would separate out the snippet generation from the choosing of which spec you want to generate. It would make moving from one spec to another as simple as switch to a different gradle plugin or in the maven plugins case just changing a configuration option.
If you are supportive of this approach I'd be willing to help out with it.
First step I think is making similar changes to this repository as I just did to restdocs-openapi to create a separate restdocs-raml-generator project. Then we would want to separate out the model and combine the model with the one in restdocs-openapi, probably moving it to a new repository in the process. Finally we would combine the snippets and move them to that new repository.
We started with restdocs-raml and later found that the OpenApi tooling space is so much more mature. So we dropped restdocs-raml and went for restdocs-openapi. The resource snippet in restdocs-openapi is really specification agnostic. Which is much better than what we did in restdocs-raml. It is just a dump for all the information regarding an API operation
With your changes in restdocs-openapi
we now have a nice separation between the API specification generator and the plugins. So we could easily go the route towards multi-spec support.
It is just that we at epages are not too interested in RAML-support anymore. Also we have some interest in backward compatibility of the stuff that is already there. I would not do such a change in restdocs-raml - I would rather move a restdocs-raml-generator
into what is now restdocs-openapi
. But than we also need to rename the repo (into e.g. restdocs-api-spec
) and the module restdocs-openapi
. This would surely cause some changes in our internal code that depends on this stuff.
On the other side restdocs-openapi
would be a more attractive open source project with these changes. And I would really like to see this happening.
I think I need to take this up for a discussion in my team and decide this together.
Sounds good. Just let me know if I can do anything to help!
We should add a maven plugin that does what the
restdocs-raml-gradle-plugin
does at the moment so also maven users could use the project.