Redocly / Redocly/redoc

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

Open
#2,475 4 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names the existing webhook feature as the closest related work; start by reviewing how that feature documents top-level items. Define how standalone objects should be identified and shown with tags but without verbs, and consider how the result avoids confusing them with webhooks.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.