Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Deleted user
0 / 0 points
Next:
badges earned

Your Points Tracker
Challenges
Leaderboard
  • Global
  • Feed

Badge for your thoughts?

You're enrolled in our new beta rewards program. Join our group to get the inside scoop and share your feedback.

Join group
Recognition
Give the gift of kudos
You have 0 kudos available to give
Who do you want to recognize?
Why do you want to recognize them?
Kudos
Great job appreciating your peers!
Check back soon to give more kudos.

Past Kudos Given
No kudos given
You haven't given any kudos yet. Share the love above and you'll see it here.

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

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.

Like robert Mugabuhamye likes this

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

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

@mcassidy  this did the job for me thanks

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

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
Published in Confluence

🥓🙅🏻‍♀️ Meet-less May Badge!

Hello Confluence Community!  What if i told you that you could have a healthier life and be 100% meet-less? This month, we're promoting a healthy, balanced work diet with Confluence. (Read m...

283 views 3 17
Read article

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