Atlassian REST API Browser doesn't show Java Doc Comments

Confluence Development Confluence Data Center
,
1

Hi REST Service Developers,

I am trying to generate documentation from the Javadoc comments of a REST Service (for Confluence 9.1.x with Java 17) to be rendered in the Atlassian REST API Browser (RAB).

The problem is already described in Atlassian REST API Browser dosn't show Java Doc Comments. Although the API is properly documented in Javadoc, the RAB shows nothing.

When starting AMPS/Atlassian SDK 9.1.1, I get the following written to the build output:

[INFO] --- confluence:9.1.1:generate-rest-docs (default-generate-rest-docs) @ <SNIP> ---
[INFO] Skipping REST documentation generation as it is not supported on Java 13 or greater

I have found that the issue is reported with RAB-33 and AMPS-1668 explains why this function has been removed:

If Java 13 or greater is used for generating rest documentation, 
it will fail because in JDK 13 the support to com.sun.javadoc API was removed.

Unfortunately the current documentation does not provide any information on how we are supposed to handle this:

Am i missing something? Is there some configuration trick or other tooling that would provide the documentation in the Atlassian REST API Browser? What is Atlassian’s recommendation here?

Cheers,
Robert

2

From the documentation you have linked:

You can also include a custom application-doc.xml file in your src/main/resources/ folder that can provide any custom static documentation in the WADL file.

Have you tried this?

Never used it. Maybe provide an update here, if you got it working.

1 Like
3

We’ve moved from using this to Swagger and putting our REST API documentation on developer.atlassian.com. We’re no longer using REST API Browser internally, with time we’ll EoL it. I recommend instead doing the same, use swagger to generate the docs and host that on your website.

Generating that file that RAB picks up relied on a lot of patching we did to a Jersey 1 module, even with that the RAB never really worked right and was hard to generate docs for. It was a cool idea 10+ years when it was built, but the industry has moved on.

1 Like
5

So, why not integrate documentation generation into AMPS and embed it somehow into the application?

The REST API browser is more than just “documentation”, i.e. a very good tool for discovering available APIs at all…

6

Not totally opposed to the idea, but …

Discovery is mostly solved by our products eventually getting to full coverage (some gaps ATM) which will put almost everything in one place and checking directly with installed apps. Arguably having the REST API documentation on a website is more easily discoverable. Not even sure improving discovery makes sense when customers are now pretty mature in their setups.

It’s honestly not one of the top of mind things we’re hearing from customers. Of course, like always if there’s a JAC ticket and it gains enough interest relative to other things we’ll reconsider.

7

We finally also decided to integrate a Swagger UI into the admin section of our apps. The REST API Browser is a cool tool to get everything setup quickly. Swagger seems to provide more options to users to try out the API provided by our apps. Our move towards Swagger was also based on the possible discontinuation of the REST API Browser and the lack of support of the latest Confluence version.

So it was finally time to say goodbye and to say thank you for providing this cool tool which made it so easy to provide a API documentation to users within Confluence for years!

Thank you @mkemp for your detailed explanation!

We are quite new to Swagger, but nonetheless would like to share our approach, so others may get there more quickly. We provided a sample project on Bitbucket that tries to be a somewhat minimal example of a Swagger integration using Spring Java Config. We also wrote a very short article on our blog, but all the integration questions are documented on Bitbucket.

There is certainly room for improvement. Any feedback is welcome. :slight_smile:

2 Likes
8

Very cool, thanks for sharing!!

We did find that we couldn’t quite put all the details we wanted into swagger and some of the annotations are kind of verbose so BBDC does have a custom set of annotations and processor. I’m not sure if it’s relevant to share more publicly. Maybe some of them got pushed upstream? I’ll do some digging.

There is certainly room for improvement. Any feedback is welcome. :slight_smile:

Only FE nits: could be Soy and lazily required JS using the AMD module of wrm/context-path.

1 Like
9

Hi @mkemp,

Thank you for your helpful reply!

I updated the example code to use wrm/context-path and made some minor fixes and changes including the replacement of servlets with Struts actions.

I have not yet followed your hint for using a Soy template for api-browser.vm. I am not familiar with Soy, besides using it to define blueprints (in a copy-paste manner). I understand the basic advantages and use cases as daz outlined them at Soy templates or Velocity?. I do not yet understand how to apply it here. But I will check out Writing Soy Templates in your plugin and AUI Soy. If there are further resources that would help me in this context, please share. :slight_smile:

It would also be be very helpful if you could share some best practices or public resources that you deem relevant for your design in using Swagger with your products.

Cheers,
Robert

1 Like
10

I won’t call it a best practice. We’re still figuring things out ourselves. We won’t provide any warranty or real support for it, but you can take a look at how we’re generating our documentation. https://packages.atlassian.com/maven-closedsource/com/atlassian/dc/swagger/annotations/

We’ve added our own annotations:

  • @BasePathDoc which we use for different API paths (ignoring the host)
  • @ListResponseDocs where the response is a list of some return type
  • @ResponseDoc which is because the swagger Maven plugin is not so good at figuring out alternate return types depending on the type of error

The rest of our custom annotations aren’t probably so useful to reuse since they map closely to the security levels of each individual product or they’re about common parameters.

We had forked the swagger maven plugin originally but instead we have our own OpenApiReader and specify using it in the pom.xml. This is what we do in Bitbucket

<plugin>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <configuration><readerClass>com.atlassian.bitbucket.server.swagger.processor.BitbucketProcessor</readerClass>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.atlassian.bitbucket.dc.swagger</groupId>
            <artifactId>processor</artifactId>
            <version>${bitbucket-swagger-processor-version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>resolve</goal>
            </goals>
        </execution>
    </executions>
</plugin>

That’s all I can think of for now, if you ever get stuck with Soy feel free to make a new thread and then we can figure out what needs to change in the public documentation.

For the sake of the example plugin, no worries

1 Like