Redocly / Redocly/redoc

Support showing SchemaDefinitions in YAML

Open
#1,817 2 comments 5 reactions 0 assignees View on GitHub

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
Screen Shot 2021-12-01 at 6 04 00 PM

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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.