Render model definitions

[adamsoffer]

Is it possible to render model definitions from an openapi spec using this plugin? I noticed this is something redocusaurus plugin supports.

[welcome-to-palo-alto-networks[bot]]

:tada: Thanks for opening your first issue here! Welcome to the community!

[sserrata]

Hi @adamsoffer, thanks for the suggestion. I am familiar with how ReDoc and Swagger UI render models. That said, I don't have any personal experience actually using them. Can you describe how you use model definitions or how they would improve the experience for someone else?

Note: our plugin attempts to fully resolve schemas, including following any $ref pointers and merging allOf. The final representation of the schema should, in effect, be a representation of the model/component.

[colin-mckibben-sp]

Hi @sserrata. I'm also interested in support for model definitions. At SailPoint, we use model definitions in our Event Triggers API collection to expose the input/output schemas for each trigger. Model definitions help us document the input/output schemas of each trigger directly in the open API spec in a way that they can be linked to. For example, we have two places we link to our trigger models: In the description of the Trigger collection, and in the extended docs for each trigger. Model definitions also allow us to define a schema in one place rather than redefining it in the extended docs and the API spec.

[sserrata]

Thanks @colin-mckibben-sp, I appreciate the additional context and link to examples. I downloaded the SailPoint API spec for reference. I think it's something we can support but I am not certain that every user will necessarily want to generate models in all cases.

That said, we might explore introducing a CLI option like --include-models or -m that determines whether or not to generate them. Additionally, I think it makes sense to group/keep all the models together under a category. That or we can explore generating a separate sidebar slice just for the models.

[daltonconley]

@sserrata Has there been any progress on this?

[sserrata]

Hi @daltonconley, nothing yet. Hoping to get started on this one for the next minor release.

[etiennea]

• 1 for this one

[sserrata]

Now available in both v2.1.3 and 3.0.0-beta.10