Does confluence support the display of Swagger?
Asked by 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?


Answers:
author: mcassidy
body: 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](/t5/user/viewprofilepage/user-id/1345631) 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>" /\>

<br />

\<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\>

comments: author: Herman Esterhuizen
body: How did you use this in confluence


author: tuxfy
body: 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.


author: mcassidy
body: [@Herman Esterhuizen](/t5/user/viewprofilepage/user-id/1192018) [@tuxfy](/t5/user/viewprofilepage/user-id/3429273) 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.


author: tuxfy
body: Thanks. This works.

Only one correction

## [@Param](https://community.atlassian.com/t5/user/viewprofilepage/user-id/1345631) SpecURL:title=Spec URL\|type=string\|required=true\|desc=The URL to render

[@Param](/t5/user/viewprofilepage/user-id/1345631) has to be [@Param](/t5/user/viewprofilepage/user-id/1345631) (small p)

Thanks again.


author: BOX Admin
body: 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. {#toc-hId--596918993}

#### 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).
<br />
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 {#toc-hId-1890593840}


author: mcassidy
body: [@BOX Admin](/t5/user/viewprofilepage/user-id/3212084) are you able to provide you swagger json?


author: robert Mugabuhamye
body: [@mcassidy](/t5/user/viewprofilepage/user-id/1036671) this did the job for me thanks


author: Peter
body: OpenAPI/Swagger plugin: <https://marketplace.atlassian.com/plugins/net.oharagroup.confluence.plugins.confluence-open-api/cloud/overview>

comments: author: Andrey Stepanov
body: 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>


author: Svitlana Kuznietsova
body: I've used this plugin for cloud confluence: [https://marketplace.atlassian.com/apps/1220001/visualize-openapi-swagger-documentation?hosting=cloud\&tab=overview](https://marketplace.atlassian.com/apps/1220001/visualize-openapi-swagger-documentation?hosting=cloud&tab=overview)

comments: author: Louie Almeda
body: This works extremely well. This is the way to go. ?


author: Aaron Knight
body: You can use my project [Swagger Confluence](https://cloud.slkdev.net/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:

comments: author: Rajeev Agile Ravishankar
body: 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.


author: Rishab Garg
body: Aaron,

Does your plugin work with Confluence cloud?

Thanks!


author: Alexander Kueken
body: 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.

comments: author: Laura
body: Hi Alexander,

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


Tags: confluence-development

swagger