The following is a list of potential Frequently Asked Questions and their answers.

Q: Why would I want to use a prefix?

Titles in a Confluence space are globally unique. You cannot have two articles titled “Overview”, for example, within the same space– even if they have different parents.

Using a prefix can help ensure that articles with common names become unique and do not accidentally overwrite another article. If you don’t want to use a prefix, either ensure that your articles will not have any naming conflicts, or create a dedicated space for each API documentation.’

Q: Why is the API documentation in alphabetical order? Some of the order doesn’t make sense this way - ex: Defintions is before Overview

Confluence forces alpha-sort by default on new articles. While you can manually re-order them in the Confluence UI afterward, the order cannot be controlled by the REST API. This means that the published articles will unfortunately be alphabetically sorted. You can mostly work around this if you use the numeric prefixes option.

Q: I turned on numeric prefixes. Why are my Path entries not in the same order when I republish?

At the time of the current release, one of the upstream libraries of Swagger Confluence, Swagger2Markup, has an issue in their current release where the order of the Paths page is not deterministic.

A bug was filed in the project recently, and has since been fixed, but a new version is not out yet. When a new version is released that contains this fix, Swagger Confluence will be updated accordingly.

Your best bet is to disable numeric prefixes; even if the above issue is fixed, the prefix numbers may change when APIs are added or removed within the document. Since Confluence Articles are unique within a space, if there is no prefix the link will never change as long as that piece of the API exists. The trade off unfortunately is that Confluence will them alpha-sort your articles by default. There is no way to work around this currently.

Q: Swagger Confluence threw an exception because it does not have permission to delete articles. Why does Swagger Confluence need delete permissions?

Swagger Confluence only needs delete permissions if you are using the individual pagination mode. The reason delete is needed in this case is because at this level, every API element is its own page.

If you delete an element, the doc page should also get deleted. Similarly, newly entered elements could cause the numeric prefixes to be re-ordered. To avoid these issues, Swagger Confluence does a “clean” publish at the individual page level, where it deletes all of the individual level pages and recreates them.

The API is queries for these pages by matching against the category pages that Swagger Confluence created for itself on the previous run. Only sub-pages of these auto-generated pages are deleted.