Duplicate operationId's

Currently Tapir is rendering specs with duplicate operationId’s. According the OpenAPI specification this should not be allowed, they should be unique. I think spec generation should fail, right?

Reusing endpoint definitions and patching them is not uncommon (at least how I am using them).
I have a set of endpoints which I want to duplicate with some different paths/options. I can prefix the endpoint-paths easily by mapping a list of endpoints and call prependIn.
However, the operationId I cannot patch, only override. What if endpoint names (operation-ids) can be prefixed/suffixed/tweaked? Is it currently possible? Is there any reason why this cannot be implemented?

Looks like I can tweak the info field of and Endpoint. Perhaps it can be a method on the endpoint itself to tweak it?

Something like:

def prefixName(n: String): ThisType[R] = withInfo(info.copy(name = Some(n + info.name.getOrElse(""))))
def suffixName(n: String): ThisType[R] = withInfo(info.copy(name = info.name.map(_ + n)))

I am also missing a way to configure my openapi generator to render all names snake, kebab, camel etc. Is it missing?

There’s a deduplication step so operation ids should be unique. Can you provide a reproducing example, which demonstrates how this fails?

As for the names, there’s some options which you might change, I think schemaName is what you are looking for: Generating OpenAPI documentation — tapir 1.x documentation

Is this duplicationstep explicit? I just rendered some specs where I have named all my endpoints the same.

No, it’s part of the process: tapir/docs/apispec-docs/src/main/scala/sttp/tapir/docs/apispec/schema/SchemasForEndpoints.scala at master · softwaremill/tapir · GitHub

It says SchemaKey, is that also used for operationId’s?

schemaName is not what I am looking for I think. That is how the schemas are named, this is purely about operationId’s. If the spec has duplicate operationId’s then e.g. my Zodios client generators fails to generator all of the endpoints, it silently drops the duplicates.

The EndpointVerifier test does also not catch duplicate operationId’s.

Is there a specific test in the repo for these operationId’s? Then I can perhaps fiddle a bit with that to see if I can demonstrate it (and fix it perhaps).

Added a test to the EndpointVerifier to show it is not detecting duplicate names: test(testing): add test to detect duplicate endpoint names by ThijsBroersen · Pull Request #3908 · softwaremill/tapir · GitHub

Ah yes, you are right, I misunderstood the original problem.

There’s an operationIdGenerator that you can customise in options (see tapir/docs/openapi-docs/src/main/scala/sttp/tapir/docs/openapi/EndpointToOpenAPIPaths.scala at e2f61dfa8f9019881502ae3a2af4c4cc3d42f9cf · softwaremill/tapir · GitHub), however if the endpoint’s name is explicitly set, it alway overrides the generated operation id.

So here I guess the solution would be “do not use duplicate endpoint names”, as they are then used for operation ids (and I think that’s their only usage). Unless you have a use-case for using the same name multiple times?

And you are right of course that this should be caught by the EndpointVerifier - thanks for the test - maybe you could contribute the implementation as well?

Yes, I can. I will take a look later this week.

1 Like