JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow


Global Services Authentication Objects Flows
@ApiGlobal@Api@ApiAuthNone@ApiObject@ApiFlowSet
@ApiGlobalSection@ApiMethod@ApiAuthBasic@ApiObjectField@ApiFlow
@ApiChangelogSet@ApiVersion@ApiAuthBasicUser@ApiFlowStep
@ApiChangelog@ApiHeaders@ApiAuthToken
@ApiMigrationSet@ApiHeader
@ApiMigration@ApiParams
@ApiPathParam
@ApiQueryParam
@ApiBodyObject
@ApiResponseObject
@ApiErrors
@ApiError

@ApiGlobal

This annotation has to be used on a class dedicated to global api documentation
LevelClass
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
LevelAnnotation
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
LevelClass
Property changelogs An array of @ApiChangelog annotations

@ApiChangelog

This annotation is to be used inside an annotation of type ApiChangelogSet
LevelAnnotation
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
LevelClass
Property changelogs An array of @ApiChangelog annotations

@ApiMigration

This annotation is to be used inside an annotation of type ApiMigrationSet
LevelAnnotation
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
LevelClass
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
LevelMethod
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
LevelClass, 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
LevelClass, Method
Property headers An array of ApiHeader annotations

@ApiHeader

This annotation has to be used inside an annotation of type @ApiHeaders
LevelAnnotation, 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
LevelMethod
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
LevelAnnotation, 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
LevelAnnotation, 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
LevelMethod, 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
LevelMethod
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
LevelClass, 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
LevelAnnotation
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
LevelClass, 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
LevelClass, 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
LevelAnnotation
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
LevelClass, 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
LevelClass
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
LevelField
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
LevelClass

@ApiFlow

This annotation is to be used on a method (typically on a class dedicated to flow description) and contains an array of @ApiFlowStep
LevelMethod
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
LevelAnnotation
Property apimethodid The api method identified by this id is the method used in the flow step

Version 1.2.17 | Licensed under MIT License

GitHub Project | Issues