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 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?
Mark your APIs with one of these annotations: @PublicApi or @ExperimentalApi. Any resource without one of these two annotations will be treated as private.
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.
