Document standalone objects (without an operation/path/webhook)

[kylejmcintyre]

Document standalone objects (without an operation/path/webhook)

[jeremyfiel]

Can you give an example OAS description and your expected behavior?

Sounds like you want to externalize your schemas, which can be done a multitude of ways.

First, you can use OAS 3.1.0 and only define the components section and then reference the components from other OAS descriptions .

# components-only.yaml
openapi: '3.1.0'
info:
  title: test
  version: '1.0.0'
components:
  schemas:
    yourSchemaHere: {}
    anotherSchemaThere: {}

# my-real-api.yaml
openapi: '3.0.3'
info:
  title: test
  version: '1.0.0'
paths:
  '/thing':
    get:
      responses:
        '200':
          description: a response with a reference to a components only file
          content:
            'application/json':
              schema:
                $ref: 'components-only.yaml#/components/schemas/yourSchemaHere'

Secondly, you can use external JSON Schema schemas. these can be written in JSON or YAML

openapi: '3.1.0'  either OAS 3.0.x or 3.1.x will work with external JSON Schema schemas. 
info:
  title: test
  version: '1.0.0'
components:
  schemas:
    yourSchemaHere: 
      $ref: 'yourSchemaHere.schema.json#'
    anotherSchemaThere: {}

## filename:  "yourSchemaHere.schema.json"
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "yourSchemaHere",
  "type": "object",
  "properties": {
    "some_prop": {}
  }
}

# a yaml variation of the same JSON Schema.   "yourSchemaHere.schema.yaml"
$schema: 'https://json-schema.org/draft/2020-12/schema'
title: yourSchemaHere
type: object
properties:
  some_prop: {}

[kylejmcintyre]

Thanks for the response! We're already making heavy use of components/refs in our OAI schema. Let me try to give a more descriptive version of the feature which is probably off-base but hopefully illustrative:

• Support an extension property like `x-redoc-exposed-component-tag' that would take a tag value like operations do
• redoc discovers components with the above tag and adds that as a top-level entry in the redoc UI under the appropriate tag (regardless of whether or not the component is referenced directly or indirectly by an op),
• Instead of having an HTTP Verb or 'Event' as their descriptor, it just says something like 'Object', 'Schema' or 'Component'.
• Basically we really like your drilldown for exploring schemas and want to leverage it without having to declare an operation (API or webhook)

Here's an example where I'm declaring something as a webhook that really isn't so that people can explore the object schema. We'd like to use this for a variety of purposes including documenting analytic events (not webhooks), data dictionaries & objects that are used in our scripting framework.