Document REST Resource

#1

Hello.
I’ve created a REST Resource in my plugin and now want it to be documeted. My code looks like this:

@Path(ResourcePatterns.REPOSITORY_URI)
@Singleton
public class MyResource {
   /**
     * Resource description
     * @param myParam this is param description
     */
    @GET
    @Path("/mypath")
    public Response myMethod(@Context ContainerRequest request,
            @Context Repository repository,
            @PathParam(ResourcePatterns.PROJECT_KEY) String projectKey,
            @PathParam(ResourcePatterns.REPOSITORY_SLUG) String repositorySlug,
            @QueryParam("myParam") String myParam)
    { return ResponseFactory.ok().build(); }
}

When I install my plugin, I see this resource in Rest Api Browser, but there is no description of a method or its parameter.
This page https://developer.atlassian.com/docs/atlassian-platform-common-components/rest-api-development/documenting-your-apis-with-the-atlassian-rest-api-browser tells that I only need javadoc comment to add a description and I’ve created one.
What is wrong?

2 Likes
#2

Sorry if this an obvious question, but just to double check, have you unticked the ‘public apis’ checkbox?

Screenshot 2017-11-16 10.34.17.png1196×338 39.2 KB

The documentation you linked to says

Mark your APIs with one of these annotations: @PublicApi or @ExperimentalApi. Any resource without one of these two annotations will be treated as private.

#3

Yes, I have.
I see my resource in rest api browser, it does what it should do. But there is no description of methods or its parameters.

1 Like
#4

Same here. I think some intermediate step is missing (in Atlassian docs?) to make it work, becase javadoc is not generated during regular plugin build, so this information is not even stored inside of plugin.

After studying the code of RAB, it seems that RAB expects to find this information in files application-doc.xml, application-grammars.xml and resourcedoc.xml. So these should be created during plugin build, but they are not.

A hackish way is to add those files to plugin resources and fill all information by hand, but I very much hope that that’s not a “correct” way to do it. And parameter descriptions are not shown for all methods, even standard bitbucket’s ones.

1 Like
#5

@khughes - in general the add-on REST resource URIs show up in the REST API browser, however any java-doc efforts as described in https://developer.atlassian.com/server/framework/atlassian-sdk/documenting-your-apis-with-the-atlassian-rest-api-browser/ are NOT reflected.

  1. Method descriptions are not displayed
  2. Parameters are not displayed
  3. Responses are not displayed