Add a maven plugin

[mduesterhoeft]

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.

[klieber]

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

[mduesterhoeft]

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.

[klieber]

Sounds good. Just let me know if I can do anything to help!