-
Notifications
You must be signed in to change notification settings - Fork 2.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document standalone objects (without an operation/path/webhook) #2475
Comments
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-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: {} |
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:
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. |
Describe the problem to be solved
We use OpenAPI to describe all APIs and objects in our system. Often we have an OpenAPI definition for a particular object that isn't necessarily part of an API or Webhook request/response that we'd like to call out in our documentation. For example, our product allows customization through a lightweight python runtime that we pass deeply nested compositional objects to. I'd love to be able to use redoc to document the shape of those objects.
Describe the solution you'd like
I guess it would be an OpenAPI extension that would allow me to identify objects that I want to be documented at the top-level. They should still have tags but wouldn't have verbs. The webhooks enhancment was sort of inline with what we'd like, but they're not always webhooks either.
Describe alternatives you've considered
Using your webhook feature to document things that are not actually webooks, leading to some confusion.
Additional context
The text was updated successfully, but these errors were encountered: