JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow


Annotation on an exposed rest service class

Here is an example on how to use JSONDoc annotations on your controller classes:

package org.jsondoc.sample.controller;

import org.jsondoc.core.annotation.Api;

@Api(name = "city services", description = "Methods for managing cities")
public class CityApi {
        // ...
}

This is the minimum required to let JSONDoc know that there is an API to be documented. You can enrich the documentation by using other annotations:

package org.jsondoc.sample.controller;

import org.jsondoc.core.annotation.Api;

@Api(name = "city services", description = "Methods for managing cities", group = "Geography")
@ApiVersion(since = "1.0", until = "2.12")
@ApiAuthNone
public class CityApi {
        // ...
}

Annotations for exposed methods of a rest service class

Here is an example on how to use JSONDoc annotations on your api methods:

package org.jsondoc.sample.controller;

import org.jsondoc.core.annotation.ApiError;
import org.jsondoc.core.annotation.ApiErrors;
import org.jsondoc.core.annotation.ApiMethod;
import org.jsondoc.core.annotation.ApiParam;
import org.jsondoc.core.annotation.ApiResponseObject;
import org.jsondoc.core.pojo.ApiVerb;

// ...

@ApiMethod(
        path = "/city/get/{name}",
        description = "Gets a city with the given name, provided that the name is between sydney, melbourne and perth",
        produces = { MediaType.APPLICATION_JSON_VALUE },
        consumes = { MediaType.APPLICATION_JSON_VALUE }
)
public @ApiResponseObject City getCityByName(@ApiPathParam(name = "name", description = "The city name") String name) {
        // ...
}

Notes:

  • When verb is not specified, the resulting will be GET
  • When response status code is not specified, the resulting will be 200
  • If path is not specified in @ApiMethod, then an error will be shown in the JSONDoc UI and the playground will not work
  • If produces is not specified in @ApiMethod, then a warning will be shown in the JSONDoc UI, but the playground may still work
  • If description is not specified in @ApiMethod, then an hint will be shown in the JSONDoc UI, suggesting to add it for a more meaningful documentation
  • If name is not specified in @ApiPathParam, then an error will be shown in the JSONDoc UI and the playground will not work
  • If description in @ApiPathParam is not specified, then an hint will be shown in the JSONDoc UI, suggesting to add it for a more meaningful documentation

Also in this case you can enrich the documentation by using annotation properties and other annotations:

package org.jsondoc.sample.controller;

import org.jsondoc.core.annotation.ApiError;
import org.jsondoc.core.annotation.ApiErrors;
import org.jsondoc.core.annotation.ApiMethod;
import org.jsondoc.core.annotation.ApiParam;
import org.jsondoc.core.annotation.ApiResponseObject;
import org.jsondoc.core.pojo.ApiVerb;

// ...

@ApiMethod(
        path = "/city/get/{name}",
        verb = ApiVerb.POST,
        description = "Gets a city with the given name, provided that the name is between sydney, melbourne and perth",
        produces = { MediaType.APPLICATION_JSON_VALUE },
        consumes = { MediaType.APPLICATION_JSON_VALUE },
        group = "Geography",
        responsestatuscode = "201 - Created"
)
@ApiAuthBasic(roles = {"ROLE_USER", "ROLE_ADMIN"}, testusers = {@ApiAuthBasicUser(username = "user", password = "123456")})
@ApiHeaders(headers={
        @ApiHeader(name="api_id", description="The api identifier")
})
@ApiErrors(apierrors={
        @ApiError(code="2000", description="City not found"),
        @ApiError(code="9000", description="Illegal argument")
})
public @ApiResponseObject City getCityByName(@ApiParam(name="name", description="The city name", allowedvalues={"Melbourne", "Sydney", "Perth"}) String name) {
        // ...
}

See the annotations page for more info about other annotations' properties that can make the documentation richer.


Version 1.2.17 | Licensed under MIT License

GitHub Project | Issues