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
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

Version 1.2.23 | Licensed under MIT License

GitHub Project | Issues