Does confluence support the display of Swagger?

[Aaron Diffenderfer]

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?

[mcassidy]

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>

[Herman Esterhuizen]

How did you use this in confluence

[tuxfy]

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.

[mcassidy]

@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.

[tuxfy]

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.

[BOX Admin]

Hi 
Many thanks for posting the Macro description
When I try it, I do get an error:

Parser error on line 36
end of the stream or a document separator is expected
Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).


When viewed in Swagger Editor, it displays fine and I am just saving the swagger.json file and uploading it to Confluence as suggested.

Any idea of the problem?
Many thanks, Rob

[mcassidy]

@BOX Admin are you able to provide you swagger json? 

[robert Mugabuhamye]

@mcassidy  this did the job for me thanks

[Peter]

OpenAPI/Swagger plugin: https://marketplace.atlassian.com/plugins/net.oharagroup.confluence.plugins.confluence-open-api/cloud/overview

[Andrey Stepanov]

If I may recommend my app as well. Hopefully it can be useful for you.

https://marketplace.atlassian.com/apps/1220001/visualize-openapi-swagger-documentation

[Svitlana Kuznietsova]

I've used this plugin for cloud confluence: https://marketplace.atlassian.com/apps/1220001/visualize-openapi-swagger-documentation?hosting=cloud&tab=overview

[Louie Almeda]

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

[Aaron Knight]

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

[Rajeev Agile Ravishankar]

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.

[Rishab Garg]

Aaron,

Does your plugin work with Confluence cloud?

Thanks!

[Alexander Kueken]

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.

[Laura]

Hi Alexander,

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