How to control the name of the schema?

[mgwoj]

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.

restdocs-api-spec/restdocs-api-spec-openapi3-generator/src/main/kotlin/com/epages/restdocs/apispec/openapi3/OpenApi3Generator.kt

Line 150 in fd7e3ba

private fun generateSchemaName(path: String): (Schema<Any>) -> String {

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

[mduesterhoeft]

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]

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]

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]

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]

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:
#97

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

[thowimmer]

PR #116 deals with this issue.

[mduesterhoeft]

closed with #126