Support showing SchemaDefinitions in YAML
Nobody has claimed this yet.
- 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're documenting some K8S CRDs using Redoc, but it appears the <SchemaDefinition> markdown helper only supports showing the model in JSON, not YAML.
We have entries likes
"tags": [
{
"name": "ConfluentRolebinding platform.confluent.io/v1beta1"
"description": "<SchemaDefinition schemaRef=\"#/components/schemas/io.confluent.platform.api.v1beta1.ConfluentRolebinding\" />",
}
(Note that the K8S CRDs auto-generate swagger (2.0), so this invokes the compatibility layer in Redoc. Hence the above is swagger 2.0 format. I'm not sure this is relevant to the implementation, but just in case)
These show up in the docs like

Describe the solution you'd like
I'd like this to show the equivalent YAML on the right panel instead, like
kind: ConfluentRolebinding
apiVersion: platform.confluent.io/v1beta1
metadata:
name: confluentrolebinding-example
namespace: confluent
creationTimestamp: null
spec:
principal:
type: user
name: test
role: SystemAdmin
status:
...
Describe alternatives you've considered
No known alternatives
Additional context
Many K8S APIs and K8S-inspired APIs prefer YAML content-type. This is both in the model object as well as in requests and responses. I don't know if requests and responses support YAML examples since we're only documenting the CRDs (models) right now. But as we continue working toward more of this "infra-as-code" approach in our APIs, more of them will likely start supporting YAML as well.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the SchemaDefinition markdown helper and inspect how its schemaRef is rendered through the Swagger 2.0 compatibility layer. Use the Kubernetes CRD example from the issue to verify that the right panel shows an equivalent YAML representation instead of JSON.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100