Need help or examples of developer portals built with JSM

[Nuno Jonet]

Hi community!

We are trying to setup a developer help center using JSM, but we are hitting a few roadblocks. 

The most frustrating block has been the apparent innability to have a Knowledge Base article that embeds an OpenAPI spec.

We tried a number of apps in Confluence that use different renderers for OpenAPI (e.g. Swagger, Rapidoc, Spotlight), and they work in Confluence. But when that page is viewed from a Help Center, the OpenAPI doesn't work.

Since it doesn't work for multiple apps, this feels like a limitation of JSM rather than an issue with the apps. 

Do you have any advice and some examples of how you've setup a developer-oriented help center, with things like OpenAPI specifications rendering correctly?

[Sarp Egemen]

Hi @Nuno Jonet ,
Welcome to the Atlassian Community!

If the apps you tried only work in Confluence, you might consider using Confluence directly as your knowledge base.

Setting pages, directories, or even the entire space to public access is possible. Let me know if you need help making them public.

[Nuno Jonet]

Hi @Sarp Egemen , thanks for the reply and suggestion.

We did consider serving the content directly from Confluence.

Unfortunately, we want to have authenticated access to the portal, as a lot of the info there is proprietary. We noticed that we could enable Guest access to the space, but there's a limited number of Guests allowed, which is based on the number of active licenses. 

Additionally, we tried using tools like Refined and Scroll Viewport to publish the Confluence content, only to hit the same issue, the content of the OpenAPI spec renderer just does not show in those pages.

I was quite surprised to see the same outcome with a Help Center in JSM.

Thanks again!

[Scott]

Hi @Nuno Jonet ,

Additionally, we tried using tools like Refined and Scroll Viewport to publish the Confluence content, only to hit the same issue, the content of the OpenAPI spec renderer just does not show in those pages.

I'm not sure if you specifically tried our app, Open API Documentation for Confluence , but just to let you know that we worked closely with the folks over at K15t (makers of Scroll Viewport) and I can confirm that our app does work when published using Scroll Viewport.

Just thought I'd point that out for anyone else who might be facing a similar issue.

Kind regards,

Scott.

[Nuno Jonet]

Hi @Scott ,

That's actually very helpful to know. We did not try your specific app so we will give it a go. I was hoping to use a different rendered than Swagger (I find it outdated), but this is way better than nothing.

As a suggestion, please consider other renderers for your app, e.g. Redocly.

Thanks,

Nuno