Distinct Pages By Discriminator

[SJrX]

Is your feature request related to a problem?

We have a RESTful API and in some cases an endpoint has a few different mutually exclusive representations, maybe an example might be from the Showcase, the "Debug Host" command: https://docs.defined.net/api/host-command/

Other than these endpoints using the same URL they are essentially otherwise disjoint conceptually. The way the UX is laid out know, you just have a bunch of oneOfs in the response and request, this makes things compressed when the endpoint has more differences than similarities.

Describe the solution you'd like

So OpenAPI prevents you from having multiple definitions for the same route/method. But I guess would be nice is a way via OpenAPI extensions and configuration, have distinct pages be rendered based on the discriminator value, it would be all extension based, and then instead of renedring the pages as one page with just different one ofs, we could make it easier for users to understand and digest the endpoint.

For instance in the Debug Host, above, lots of the details about each command you can run, just have to be buried in the schemas of the objects, and the high level more visible text has to be general, so if you are trying to Create a Tunnel, the only high level thing it can say is

Successful operation. 'StreamLogs' will return a newline-delimited JSON stream, the rest return standard JSON.

What' I'm proposing would allow for something like:

- Hosts
- Create host
- List host
- ....
- Stream Logs
- Create Tunnel
- Print Tunnel
- Print Cert
- Query Lighhouse

Or maybe

- Hosts
- Create host
- List host
- ....
- Debug
  - Stream Logs
  - Create Tunnel
  - Print Tunnel
  - Print Cert
  - Query Lighhouse

Describe alternatives you've considered

I tried to see if there was some way to do this already, but after 10 minutes didn't see anything.

Additional context

Primarily for us we have migrated from hand rolled API documentation to OpenAPI spec based stuff, but we have some APIs where admittedly the way things are compressed makes it very difficult for users to understand, and in some cases some feedback has been that the old docs were better in a few cases.

[sserrata]

Hi @SJrX, with OpenAPI there's typically more than one way to describe an endpoint...Have you looked into the discriminator pattern to see if it could add clarity?

• https://swagger.io/docs/specification/v3_0/data-models/inheritance-and-polymorphism/#discriminator
• https://redocly.com/learn/openapi/discriminator#when-to-use-the-openapi-discriminator

Something else I noted - the command property could be an enum and StreamLogs and DebugStack are the only odd ones out in terms of schema...that said, you could also explore additionalProperties which is intended to support unstructured data. The downside is you would lose some fidelity and might need to offer more examples to fill in the gaps.

Another option would be to redesign the API endpoint request schema to better accommodate the "minor" differences in StreamLogs and DebugStack...in the end, it's about choosing the description that offers the clearest documentation for end users.

[sserrata]

Forgot to mention our plugin supports x-enumDescriptions, in case you do decide to explore command as an enum.

Example:

• docusaurus-openapi-docs/demo/examples/petstore.yaml

  Line 409 in 128d240

  x-enumDescriptions:

• https://docusaurus-openapi.tryingpan.dev/petstore/find-pets-by-status

[SJrX]

Thanks @sserrata ,

I'm familiar with discriminators, and the "Debug Host" command I posted is not my OpenAPI spec just a reference example, for something that happens.

If we look at how Debug Host is rendered.

The main description has to be super generic, the Request and Responses, are up to the user to correlate and specific details
are cramped in the body.

In this case, it's arguable that distinct endpoints would be better described by essentially distinct pages, but for reasons we are stuck with one URL, namely that we are a REST API, and the endpoint is polymorphic and we feel it would be better to describe each subtype distinctly instead of cramped in all one page.

I was hoping to find a way to get more than one page per URL.

Additionally thank you for the x-enumDescriptions tip, that will help (in other cases), but not for this issue.