Schema only documentation

[lukaslentner]

Hi,

I have cases where I only want to document schemas, so the openapi property "paths" is empty. The Cases are File-Based-APIs like Config Files and other APIs that will take a JSON string. I want to document the structure without having to add a rest operation.

Right now it looks like that redoc ignores such "unused" schemas.

Is it possible to disable that ignoring?

If not already, please consider this a feature request.

Thankx Lukas

[baboonmaj]

In OpenAPI 3.1.0 paths are optional !!! https://stoplight.io/blog/difference-between-open-v2-v3-v31/#paths-are-now-optional

So, as a workaround you can document non REST APIs as WebHooks which is identified by name rather than an URL.

I think Stoplight is working towards supporting OpenAPI 3.1.0. But if you are not looking for a SASS then you can look at RapiDoc they are already supporting OpenAPI 3.1.0

[handrews]

I am using ReDoc for this right now, actually (not public or I'd link it). But I got it from the demo code, specifically:

tags:
  - name: pet
    description: Everything about your Pets
  - name: store
    description: Access to Petstore orders
  - name: user
    description: Operations about user
  - name: pet_model
    x-displayName: The Pet Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Pet" />
  - name: store_model
    x-displayName: The Order Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Order" exampleRef="#/components/examples/Order" showReadOnly={true} showWriteOnly={true} />
x-tagGroups:
  - name: General
    tags:
      - pet
      - store
  - name: User Management
    tags:
      - user
  - name: Models
    tags:
      - pet_model
      - store_model

You can see how they embed a React element in the tag description- you can also put regular text above it. The Models tag group then pulls that in and "tricks" Redoc into rendering the schema as part of what it thinks is the tag description. I have a dummy API endpoint in mine to make OAS happy, but I don't include it in any tag or tag group so it's not rendered.

There are some quirks- the description field of a schema displayed like this gets ignored, I guess because that element assumes that whatever called it displayed that. So I had to move that text up into the tag description above the react element.

It works pretty well. It's not perfect, but it's close enough to what I needed.

[hheavener-kyd]

@handrews can you tell me where to find other tags like <SchemaDefinition> that can be used in redoc?

[handrews]

@hheavener-kyd I'm afraid I don't remember at this point. I think I just found them by poking around? I haven't looked at this in a year.