@ApiGlobal

This annotation has to be used on a class dedicated to global api documentation

Level

Class

Property

sections

An array of @ApiGlobalSection annotations

@ApiGlobalSection

This annotation has to be used in a ApiGlobal annotation. It represents a block of information of the same context like http verbs, authentication, common headers, etc

Level

Annotation

Property

title

The title of the section, for example "Authentication"

paragraphs

An array that can be made of two things: a text (may contain html tags) or a path to a file in the classpath, containing a text. In this case the array item should have the /jsondocfile: prefix, for example: /jsondocfile:/jsondoc/global-verbs.html

@ApiChangelogSet

This annotation has to be used on a class dedicated to changelog documentation

Level

Class

Property

changelogs

An array of @ApiChangelog annotations

@ApiChangelog

This annotation is to be used inside an annotation of type ApiChangelogSet

Level

Annotation

Property

version

Api version this changelog refers to

changes

List of changes introduced in this api version

@ApiMigrationSet

This annotation has to be used on a class dedicated to migrations documentation

Level

Class

Property

changelogs

An array of @ApiChangelog annotations

@ApiMigration

This annotation is to be used inside an annotation of type ApiMigrationSet

Level

Annotation

Property

fromversion

Source api version

toversion

Target api version

steps

Steps needed to migrate from source api version to target api version

@Api

This annotation has to be used on your controller class in an MVC pattern. It describes in a few words what the API does

Level

Class

Property

name

The name of the API

description

A description of what the API does. This can contain html tags, that will be properly rendered in the UI

group

Semantic grouping this API belongs to. For example it is possible to have a Geography group which will contain the City API and the Country API

visibility

Specifies the visibility of this api: PUBLIC or PRIVATE

stage

Specifies the development stage for this api (PRE-ALPHA, ALPHA, BETA, RC, GA, DEPRECATED)

@ApiMethod

This annotation describes your exposed methods in a generic way: which verb has to be used, which is the path for the call, which type it accepts, which one produces, etc

Level

Method

Property

path

The relative path for this method (ex. /country/get/{name}). The value of this attribute is used in the UI when the displayMethodAs configuration property is set to URI

summary

A short description of what the method does. The value of this attribute is used in the UI when the displayMethodAs configuration property is set to SUMMARY

description

A description of what the method does. This can contain html tags, that will be properly rendered in the UI

verb

An array representing the request verb(s) for this method. Defaults to GET

produces

An array of strings representing media types produced by the method, like application/json, application/xml, etc

consumes

An array of strings representing media types consumed by the method, like application/json, application/xml, etc

responsestatuscode

Response status code that this method will return to the caller. Defaults to 200

id

A custom identifier to be used inside JSONDoc. This string has to be unique inside the JSONDoc documentation. It's responsibility of the documentation writer to guarantee this uniqueness

visibility

Specifies the visibility of this api: PUBLIC or PRIVATE

stage

Specifies the development stage for this api (PRE-ALPHA, ALPHA, BETA, RC, GA, DEPRECATED)

@ApiVersion

This annotation has to be used on your controller class in an MVC pattern. It describes in a few words what the API does

Level

Class, Method, Field

Property

since

The version since the method/object/class is supported

until

The version until the method/object/class is supported

@ApiHeaders

This annotation contains all the useful information to insert in the call headers. It is just a container for the following annotation, which describes headers in detail

Level

Class, Method

Property

headers

An array of ApiHeader annotations

@ApiHeader

This annotation has to be used inside an annotation of type @ApiHeaders

Level

Annotation, Parameter

Property

name

The name of the header parameter

description

A description of what the parameter is needed for. This can contain html tags, that will be properly rendered in the UI

allowedvalues

An array representing the allowed values this header can have

@ApiParams

This annotation contains a list of @ApiParam annotations. It's possible to use it at method level, enabling writing documentation for old style servlets in which methods' signatures did not allow explicit parameter specification

Level

Method

Property

queryparams

An array of ApiQueryParam annotations

pathparams

An array of ApiPathParam annotations

@ApiPathParam

This annotation describes a path parameter to be passed to the method

Level

Annotation, Parameter

Property

name

The name of the parameter, as expected by the server

description

A description of what the parameter is needed for. This can contain html tags, that will be properly rendered in the UI

allowedvalues

An array representing the allowed values this parameter can have

format

The format from the parameter (ex. yyyy-MM-dd HH:mm:ss)

clazz

Specify this element if you need to use the ApiParam annotation on the method declaration and not inside the method's signature. This is to be able to document old style servlets' methods like doGet and doPost. This element, even if specified, is not taken into account when the annotation is put inside the method's signature

@ApiQueryParam

This annotation describes a query parameter to be passed to the method

Level

Annotation, Parameter

Property

name

The name of the query parameter, as expected by the server

description

A description of what the parameter is needed for. This can contain html tags, that will be properly rendered in the UI

required

Whether this parameter is required or not. Defaults to true

allowedvalues

An array representing the allowed values this parameter can have

format

The format from the parameter (ex. yyyy-MM-dd HH:mm:ss)

defaultvalue

The default value for this parameter, if it is not passed in the query string

clazz

Specify this element if you need to use the ApiParam annotation on the method declaration and not inside the method's signature. This is to be able to document old style servlets' methods like doGet and doPost. This element, even if specified, is not taken into account when the annotation is put inside the method's signature

@ApiBodyObject

This annotation represents the object passed in the body of the requests

Level

Method, Parameter

Property

clazz

Specify this element if you need to use the ApiBodyObject annotation on the method declaration and not inside the method's signature. This is to be able to document old style servlets' methods like doGet and doPost. This element, even if specified, is not taken into account when the annotation is put inside the method's signature

@ApiResponseObject

This annotation has to be used on your method and represents the returned object

Level

Method

Property

clazz

Specify this element if are using old style servlets which return void for methods like doGet and doPost

@ApiErrors

This annotation has to be used on your method and represents the possible errors returned by the method

Level

Class, Method

Property

apierrors

An array of ApiError annotations

@ApiError

This annotation is to be used inside an annotation of type @ApiErrors and describes the error code and the error message for the returned error

Level

Annotation

Property

code

The error code returned

description

A description of what the error code means. This can contain html tags, that will be properly rendered in the UI

@ApiAuthNone

Annotate a class or method with this annotation to specify that it does not require authentication to be accessed

Level

Class, Method

@ApiAuthBasic

Annotate a class or method with this annotation to specify that it requires Basic Authentication to be accessed. You must also specify roles that can access the method and a list of @ApiAuthBasicUser test users

Level

Class, Method

Property

roles

The role(s) a user must have to correctly access the annotated controller/method

testusers

A list of test users that can be used to test methods with different username/password/roles combinations

@ApiAuthBasicUser

This annotation is used inside @ApiAuthBasic to specify test users' username and password

Level

Annotation

Property

username

The test user's username

password

The test user's password

@ApiAuthToken

This annotation is to be used on your "service" class, for example controllers, or on exposed methods. It specifies that the controller/method needs token authentication

Level

Class, Method

Property

roles

The role(s) a user must have to correctly access the annotated controller/method

scheme

The scheme to use for the Authorization header (Bearer, JWT, etc). It can be empty

testtokens

A list of test tokens that can be used to test methods

@ApiObject

This annotation is to be used on your object classes and represents an object used for communication between clients and server

Level

Class

Property

name

The name of the object, to be referenced by other annotations with an "object" attribute

description

A description of what the object contains or represents. This can contain html tags, that will be properly rendered in the UI

show

Whether to build the json documentation for this object or not. Default value is true

group

Semantic grouping for this object. For example, you can group city and country objects in the Geography group

visibility

Specifies the visibility of this api: PUBLIC or PRIVATE

stage

Specifies the development stage for this api (PRE-ALPHA, ALPHA, BETA, RC, GA, DEPRECATED)

@ApiObjectField

This annotation is to be used on your objects' fields and represents a field of an object

Level

Field

Property

name

The display name for this field if different from the java name

description

A drescription of what the field is. This can contain html tags, that will be properly rendered in the UI

format

The format pattern for this field

allowedvalues

The allowed values for this field

required

If the field is required

order

The order by which the fields are displayed in the UI

processtemplate

Whether to process the template for this field or not. It's similar to what can be obtained using the JsonIdentityInfo/JsonManagedReference/JsonBackReference. Set this to false to avoid StackOverflow when your object has a circular or self dependency.

@ApiFlowSet

This annotation is to be used on a type (typically on a class dedicated to flow description) and will trigger scanning for @ApiFlow annotations

Level

Class

@ApiFlow

This annotation is to be used on a method (typically on a class dedicated to flow description) and contains an array of @ApiFlowStep

Level

Method

Property

name

The name of the flow

description

A description of what the flow does. This can contain html tags, that will be properly rendered in the UI

preconditions

The preconditions for this flow (example: "the user must be logged", "the user must have an administration role")

steps

An array of @ApiFlowStep annotations

group

With this it is possible to specify the logical grouping of this flow. See the same property in the @Api annotation.

@ApiFlowStep

This annotation is to be used inside an annotaion of type @ApiFlow and references a method previously documented with the JSONDoc @ApiMethod annotation in which the "id" property is specified

Level

Annotation

Property

apimethodid

The api method identified by this id is the method used in the flow step