It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Does confluence support the display of Swagger?

I have some upcoming API documentation for some services that I want to document in Confluence.  The documentation will either be written in Swagger or something like it such as API Blueprint.  Does confluence support that type of documentation?  It would be ideal if they still display like they do in Swagger UI with the overall same functionality on the page.

Or is there an alternative that would be better with Confluence?

5 answers

This works extremely well. This is the way to go. 💯

I was able to do this easily with a user macro

 

## Macro title: My Macro
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Installed by: My Name

## This is an example macro
## @Param SpecURL:title=Spec URL|type=string|required=true|desc=The URL to render

<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui.css" />


<div id="swagger-ui">&nbsp;</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-bundle.js" type="text/javascript">
</script>
<script type="text/javascript">
const ui = SwaggerUIBundle({
url: "$paramSpecURL",
dom_id: "#swagger-ui",
presets: [
SwaggerUIBundle.presets.apis,
]
})
</script>

How did you use this in confluence

Like Louie Almeda likes this

Hi, can you explain this for noob like me :)

I get an error in the menu. I think becaus I don't understand how to define the url: in a correct way.

@Herman Esterhuizen @tuxfy In confluence administration, click user macros, then choose create a user macro. Enter a name for the macro, choose escaped for the body processing option, and then paste the code from above into the template box.

When creating or editing a page, click the plus button and choose other macro from the drop down. You can search for the name of the macro that you entered previously.

You’ll get a text box to enter the url for the swagger file. The easiest thing to do here is upload you swagger file as an attachment on the page, and paste in its direct url. If your swagger file is on another server you’ll have to name sure that it is set up for CORs.

Thanks. This works.

Only one correction

## @Param SpecURL:title=Spec URL|type=string|required=true|desc=The URL to render

@Param has to be @Param (small p)

Thanks again.

In our projects we use the Swagger maven Plugin and a custom template to generate the Swagger documentation in form of Wiki Markup and import this manually into confluence. perhaps not the most fancy solution, but it works.

Hi Alexander,

Is your approach still working for you? Any chance you could give more info. on how to do this?

You can use my project Swagger Confluence to publish a static copy of the Swagger API documentation into Confluence. It will take in the Swagger YAML or JSON schema and create static documentation that it pushes directly to Confluence. At the time of writing, there is a Gradle Plugin and a Command Line Interface available. If you are on Maven, you can use the CLI jar with the exec plugin. A live demo of a few different available display options is available on the linked homepage.

Full disclosure: I am the author. I wrote this library recently after having a similar need and failing to find any good out of the box solutions available. I released this as an open source project in hope that others would find it useful :smile:

Hi Aaron,

I have a maven project and I am using Swagger for my API documentation. I would want to publish the same on our Atlassian wiki.

Can you help me with the same, is there any blog or wiki which will provide a step by step guide to do that.

Aaron,

Does your plugin work with Confluence cloud?

Thanks!

Suggest an answer

Log in or Sign up to answer
TAGS
Community showcase
Posted in Confluence

Lessons and Learnings: Six Months of Working Remote [Discussion]

Hey there, folks! For most of us, the past six months- yes, you read that right- have been a journey. More people than ever before have pivoted to working remotely, and navigating being on-scre...

2,117 views 4 5
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you