search

ePages-de / restdocs-api-spec

Adds API specification support to Spring REST Docs
MIT License
392 stars 102 forks source link

How to control the name of the schema? #78

Closed mgwoj closed 4 years ago

mgwoj commented 5 years ago

Is there any option to enforce the name of the schema in the generated contract? Currently the name is generated from the URL of the service and hash code of the schema content. https://github.com/ePages-de/restdocs-api-spec/blob/fd7e3ba46175d344ee5299b5d5aa1e0fe1403402/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt#L150

It would be great to have a control of the name of the schema for the request and response.

mduesterhoeft commented 5 years ago

Sounds like a reasonable requirement. Currently we aggregate equal schemas. So it is not necessarily the case that each operation results in a set of schemas. So I am really not sure where to put such a function.

But if you have an idea, feel free to give it a try.

mgwoj commented 5 years ago

It could be additional arguments in MockMvcRestDocumentationWrapper.document to provide name of the request and response schema. Or maybe ResourceSnippetParameters.builder() could have additional methods for specifying that?

thowimmer commented 5 years ago

I'm looking for such a functionality as well. I think the current approach is perfectly valid but it would be great to have the possibility to override the naming of a schema (using the terms of OpenAPI). I'm happy to contribute if you provide me a direction on how you'd expect this feature to be implemented.

Some keypoints which come into mind:

  1. Should follow the test driven approach (no additional annotation processing etc)
  2. Should allow to document hierarchical object structures (how about inheritance & polymorphism ?)
  3. Intermediate format (resouce.json) needs to carry those information
  4. OpenAPI Spec generators needs to read those information (if present) and generate the according documentation

Maybe we can find an approach which allows the extension of schema details in the future: Start with the naming of a schema and add additional options in the future

mduesterhoeft commented 5 years ago

Thanks for your interest in this feature @thowimmer.

Sounds like a reasonable requirement. Currently we aggregate equal schemas. So it is not necessarily the case that each operation results in a set of schemas. So I am really not sure where to put such a function.

We need to keep the statement above in mind. This surely complicates things a little.

But generally I see two options:

Make the schema name an additional parameter that you can pass in your test This would mean to add a schema name to ResourceSnippetParameters so it makes its way into ResourceModel and can thus be passed in the gradle plugin to OpenApi3Generator and OpenApi20Generator

Implement plugable naming strategies We could also invent a set of different plugable naming strategies that one would parametrize in the gradle plugin.

thowimmer commented 5 years ago

Many thanks for your proposed options. I vote for option 1 because I think that we need a richer ResourceModel which contains additional schema options, A richer resource model will allow additional features (not just naming) just like: https://github.com/ePages-de/restdocs-api-spec/issues/97

I will try to come up with a PR where we can discuss this in more detail in the next few weeks :-)

thowimmer commented 5 years ago

PR #116 deals with this issue.

mduesterhoeft commented 4 years ago

closed with #126