Developer portal mechanism to render open api specs and resolve references

[santosh_ghalsas]

Hi @Anil Sagar,

I wanted to know if developer portal uses swagger ui module to render API Specs on the portal pages. And if the spec has to use some external file references then how does developer portal resolves those references - locally or online? I mean if I need to create some reusable definitions that will be used across multiple specs then how to I host those specs - on a local directory on the same server where the portal is installed or on a repository on the internet?

Regards,

Santosh

[karlscheirer]

Since you mention module, I assume you're talking about the Drupal-based devportal.

It uses SmartDocs to render the openapi spec. It does not handle external $ref links at all as far as I know.

[santosh_ghalsas]

Hi @Karl Scheirer,

Thank you for the response.

@Anil Sagar , @gkoli@apigee.com - Can you please confirm on the referencing part. If it is not supported as of now, do we have any plan to support it in near future?

Also this smardocs module is custom built or based on some other tool?

Regards,

Santosh

[santosh_ghalsas]

@Dino, @Anil Sagar, @gkoli@apigee.com Kindly help here.

Regards,

Santosh

[santosh_ghalsas]

Hi,

Can I get reply on this if anyone has worked on this?

Regards,

Santosh

[karlscheirer]

My guess is supporting external file $refs is not on the roadmap.

The smartdocs module was loosely based on swaggerui a few years ago, but is now custom code developed by Apigee.

[#7]

i'm using smartdocs maven plugin but getting errors. please help. Thanks in advance.

https://community.apigee.com/questions/59572/getting-error-while-publishing-swagger-apis-in-api.html

[chrisnovak]

SmartDocs does not support resolving external references.

[santosh_ghalsas]

Hi @Chris Novak,

Thank you for your response. Can you please let me know if there is any plan to support this in future? If not, do we have any alternate way to achieve this?

Regards,

Santosh

[Marsh]

Remote references are useful for authoring, but a consumer who wants to understand how an API works needs a fully resolved spec. Resolving that can run into problems, such as circular references or even worse, references that are hidden behind auth. This is why we expect a fully resolved spec, and that any real-time rendering would be as performant as possible. We don't have plans to resolve those any time soon.

If you need a resolver to build into your toolchain, we recommend Sway. If you must resolve specs at the time of rendering, you may want to look into the Swagger UI Field Formatter module to see if it will help you.