Redoc: Render model definitions? (feature support)

[PedroMD]

Hello all,

Thanks for this amazing project! ;) It is now our default view engine of our Swagger spec.

As you can see in swagger-ui repo, there is a popular issue where people are asking for Models rendering, just like swagger-editor does. This would be great if it could be added to ReDoc! ;)

Thanks!

[avkonst]

I am generating a table reference with a list of models in markdown format. It seems it works. Rows in a table are hyperlinks to operations.

[sudsk]

Hi @RomanGotsiy,

Any thoughts on when this enhancement might be introduced?

Twitter APIs have something similar "object definition" - https://dev.twitter.com/overview/api/tweets

Thanks!

[RomanHotsiy]

I don't have this on the roadmap yet.
The next items are "Try it out" feature (which I have already started working on), OpenAPI 3 support + simplified branding/styling. So this feature would take some time to implement.

Although, It is not clear how to do it. OpenAPI is a bit complex.
Would be awesome if you can describe your use cases and describe how you want ReDoc to represent it.
It would help me a lot!

Thanks in advance

[sudsk]

Swagger Editor style model rendering could be good.
ReDoc Navigation could be that Models tag appear on the left pane with all models link listed under it and by clicking on a model name, the middle pane displays the model.

[K-Leon]

@avkonst Is there any chance to open source this script? I'm looking for a simple way to add the Models.

[avkonst]

@K-Leon swagger spec is the derived spec in my system. The original definition of the objects, properties and relationships of the model is in the private / internal format. This original definition format is used to generate swagger spec and necessary markdown pages. Since the format and infrastructure for managing it are deeply embedded in the private source code, so I am not able to publish anything helpful. Sorry about this.

[sudsk]

@RomanGotsiy - Found another example of schema/model definition -

https://github.com/sourcey/spectacle

[springframeworkguru]

+1 for this issue. If implemented, I'd like to see schema info. (which is missing from the following example, should have min/mix info, etc)

Here is an example from Widdershins / Slate.

[JLNNN]

+1

[cmeeren]

I'd really like this as well!

It would reduce the mental overhead of reading API docs if readers could identify which models are used in requests/responses. Currently it's "just" a list of properties, and it's entirely up to the reader to compare across operations and requests/responses to see if it's the same model.

A simple first step would be to at least show the name of the model in a request/response. Readers can then easily recognize that a certain operation returns or requests a model that's already "cached" in their minds. Easier to see patterns = easier to understand the API.

[Rikhart]

+1 for this issue, I'll like this feature help me so much, hope will be available soon

[royrico]

+1 for this issue as well!

[yvespareteum]

Models rendering is really important for us, as our APIs are based on them !
Can't wait to see that improvement delivered !!!
+1

[cmeeren]

Just want to add that the ability to render models would improve the feasibility of OpenAPI + ReDoc for documenting hypermedia APIs (where the focus is on resources and their links, not on static paths). One could create a tag for each resource, document the resource in the tag description with a rendering of the model, and then list operations on that resource as normal paths tagged with the relevant resource tag.

[bangonkali]

Is there any plan for this?

[Aykelith]

+1

[nanov]

I did some work on the matter in this PR.
My solution was to add a new markdown "extension" which leaves you the freedom to place those definitions wherever you think they are suitable.

Together with side Tag side menus, the given examples should be easy to achieve.

[tomq42]

+1 for this.
I'd like to render (selected) model definitions in the menu like operations.
Naively I'd hoped I could put a tag on the schema and it would be rendered under the tag like an operation. I can therefore create my own tag just for certain selected models.

[shaigluskin]

+1 this is key for us. Swagger UI implementation ugly, but it's there. Redoc is better with without display of model definitions we wont' be able to use it.

[jmini]

Given some spec that manages 2 entities (Task and Person): todoApp.yaml (ReDoc live demo)

My goal is to obtain a list of all models in a similar way than with Swagger-UI or Spectacle (as discussed in this issue).

If I understood it well, the approach proposed by @nanov is to add fake tags for each model and to group them under a single group called “Models” (using x-tagGroups). Each of the fake tag is calling the markdown "extension” SchemaDefinition

Diff:

--- a/OpenAPI-specs/todoApp.yaml
+++ b/OpenAPI-specs/todoApp.yaml (adding the necessary metadata)
@@ -13,6 +13,25 @@
   description: All task related operations
 - name: person
   description: All person related operations
+- name: task_model
+  x-displayName: Task
+  description: <SchemaDefinition schemaRef="#/components/schemas/Task" />
+- name: person_model
+  x-displayName: Person
+  description: <SchemaDefinition schemaRef="#/components/schemas/Person" />
+- name: error_model
+  x-displayName: Error
+  description: <SchemaDefinition schemaRef="#/components/schemas/Error" />
+x-tagGroups:
+  - name: Operations
+    tags:
+      - task
+      - person
+  - name: Models
+    tags:
+      - task_model
+      - person_model
+      - error_model
 paths:
   /task:
     get:

Result: todoAppSchemaDef.yaml (ReDoc live demo)

Maybe I missed something?

---

In my opinion, if the requirement is to display a list of all models, it would be better to just have an Global Option that does this “(e.g. list all models”), without having to add unnecessary metadata to the file.

• With a real spec the number of fake-tags might be big (our spec has about 140 Schema under components/schema)
• The additional tags might be misinterpreted by other tools.
• The resulting deep link is <server>#tag/person_model, I would prefer <server>#schema/Person

---

What are the thoughts?

[nanov]

You can do it with one tag, models, and then with markdown titles ( ## ) list all your models there.

[jmini]

@nanov: Thank you a lot for this valuable feedback.

I now have patched my original file like this:

--- a/OpenAPI-specs/todoApp.yaml
+++ b/OpenAPI-specs/todoApp.yaml
@@ -13,6 +13,25 @@
   description: All task related operations
 - name: person
   description: All person related operations
+- name: models
+  x-displayName: All Models
+  description: |
+    ## Task
+    <SchemaDefinition schemaRef="#/components/schemas/Task" />
+    
+    ## Person
+    <SchemaDefinition schemaRef="#/components/schemas/Person" />
+    
+    ## Error
+    <SchemaDefinition schemaRef="#/components/schemas/Error" />
 paths:
   /task:
     get:
@@ -283,4 +302,4 @@
         message:
           description: Short description of the error
           type: string
          example: Could not perform the task

Result: todoAppSchemaDef2.yaml (ReDoc live demo)

---

The result is already better:

• only one fake tag (with a really big description)
• The resulting deep link is <server>#section/Person, I would prefer <server>#schema/Person (but at least this is not #tag/…)

Screenshot:

---

My preferred solution would be to not have to write this models tag, but this needs a change in ReDoc.

[nanov]

It's not about a change in ReDoc, it is about giving you the freedom to choose which models in what oder are displayed and optionally giving them description, also this models could be mixed with the endpoints menus, the same way stripe does it.

[jmini]

@nanov: I understand the feature, it is just that I am more looking for an exhaustive list approach
where some HTML documentation is created for all schemas under components/schemas out-of the box (without having to write additional content to the spec that is only ReDoc specific and not stored into an extension). The element in the generated pages should be deep-linkable.

With your suggested approach, we I think we can make it work for us. But we are now speaking of creating one generic OpenAPI spec (the one we have today) and one ReDoc-specific version with the additional items required for the display we would like to get.

---

IMO it really depends how you are using authoring and using the OpenAPI spec. We are generating it, driven by our back-end. I expect the generated HTML-pages to be similar to Javadoc/tsdoc => provide an exhaustive list of the OpenAPI content (in an human readable way).

If you are closer to documentation (your OpenAPI spec is telling you a story), you might want to select the more prominent schemas and maybe add text in between.

[nanov]

With your suggested approach, we I think we can make it work for us. But we are now speaking of creating one generic OpenAPI spec (the one we have today) and one ReDoc-specific version with the additional items required for the display we would like to get.

This is not the worst approach, i think stripe does something similar.

without having to write additional content to the spec that is only ReDoc specific and not stored into an extension

I agree agree with your point, however I am not the developer behind ReDoc, and that was the way i decided in order to do as less changes as possible to the original software and make it work. I am open to suggestions which would give the functionality you are tabling about ( probably some kind of extension, x-richDescrption is one way to go but the tag stays, or maybe x-redocTags that can be used inside tag groups. ). Do you have something in mind that would also make the authoring/generation of the spec straight-forward?

IMO it really depends how you are using authoring and using the OpenAPI spec. We are generating it, driven by our back-end. I expect the generated HTML-pages to be similar to Javadoc/tsdoc => provide an exhaustive list of the OpenAPI content (in an human readable way).

If you are closer to documentation (your OpenAPI spec is telling you a story), you might want to select the more prominent schemas and maybe add text in between.

I totally agree.

[jmini]

I agree agree with your point, however I am not the developer behind ReDoc, and that was the way i decided in order to do as less changes as possible to the original software and make it work.

Understood and your feature is great!

probably some kind of extension, x-richDescription is one way to go but the tag stays, or maybe x-redocTags that can be used inside tag groups.

+1

I would prefer something solved with an extension. IMO with OpenAPI it is quite frequent that the Spec is enhanced with extensions, that only few tools will understand. This is something that already exists with x-logo.

With the current approach, the additional unused tag (not an extension) is a no-go when you browse the spec with other tools. Here a screenshot of my todoAppSchemaDef2.yaml spec with Swagger-UI (live-demo):

---

We plan to create 2 pages (one for all Schemas, and one for Callbacks -- see #411), so probably x-redocTags next to tags is the best solution.

[nanov]

@RomanHotsiy are you open to discuss this on an api/architecture level?

[RomanHotsiy]

I understand the use case and the problem for people who autogenerate their docs...

I don't quite like the idea of displaying all the schemas similar to how SwaggerUI does it. There may be lots of internal/utility schemas that do not make any sense to display under a separate menu item.

I'm not sure yet on how to solve the use case but right now I like the @tomq42 idea:

I could put a tag on the schema and it would be rendered under the tag like an operation. I can therefore create my own tag just for certain selected models.

What do you think about this idea?

[nanov]

I don't quite like the idea of displaying all the schemas similar to how SwaggerUI does it. There may be lots of internal/utility schemas that do not make any sense to display under a separate menu item.

I totally agree, that's why as explained I chose the implantation i did.

I could put a tag on the schema and it would be rendered under the tag like an operation. I can therefore create my own tag just for certain selected models.

What do you think about this idea?

I am not exactly sure how this could be implemented AFAIK schemas do not accept tag property ( x-tag could be an option ), and then you loose the ability to add text and control where exactly those schemas will be displayed. Maybe I am understanding it wrong?

[jmini]

There may be lots of internal/utility schemas that do not make any sense to display under a separate menu item.

We had the exact same discussion.

We have main models for sure, but sometime in a text-documentation (how-to, faq, architecture description) you would like to deep link to one of those secondary model. This is why we believe that we need the exhaustive list.

---

In my opinion, if ReDoc was implementing the "list-all-models-automatically" feature, this should be an option nativeScrollbars or theme. It can be false by default.

---

Because we are generating our spec, the current implementation with the Markdown Extension is OK, we can generate the all model page we need (containing a <SchemaDefinition> extension call for each model).

The only thing that we would like to get improved is the place of this page. Having to create an unused-tag is really strange. We plan to distribute our spec and we would like that it looks also good with other viewer.

Solving this with x-redocTags instead of tags would work for us.

[adamaltman]

Models are displayed inline in the Redoc documentation. So you don't need to click around. You can expand any request or response and see the model definition right there.

There may be lots of internal/utility schemas that do not make any sense to display under a separate menu item.

This is a real problem for us at Rebilly -- we have hundreds of schemas. If you look at the two most revered docs, Stripe and Twilio, they only display "resource" level objects. And they are always done in the context of the "tag" (set of closely related operations around that resource). On the other hand, these docs don't explain responses and instead mention they "return the resource", or show an example only. In the case of returning a paginator/collection, they each follow their own object style and it's defined elsewhere.

[achuprin]

Hi. Is there any way to show schema definition for concrete model of polymorphic type?
Imagine i have the following definition of polymorphic model:

Update:
  discriminator:
    propertyName: update_type
    mapping:
      update1: '#/components/schemas/Update1'
      update2: '#/components/schemas/Update2'
  properties:
    update_type:
      type: string
  required:
    - update_type
Update1:
  allOf:
    - $ref: '#/components/schemas/Update'
    - properties:
        message:
          allOf:
            - $ref: '#/components/schemas/Message'
      required:
        - message
Update2:
  allOf:
    - $ref: '#/components/schemas/Update'
    - properties:
        user:
          allOf:
            - $ref: '#/components/schemas/User'
      required:
        - user

In the sidebar i want to refer to Update2 schema:

  - name: update_model
    x-displayName: Update2
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/Update2"/>

But it renders the full Update schema where user should choose update_type in select bot to see Update2 definition.

Is it expected behaviour or am i missing something?