JSONDoc | Examples

Documenting objects

Here is an example of writing documentation for a simple class.

package org.jsondoc.sample.pojo;

import org.jsondoc.core.annotation.ApiObject;
import org.jsondoc.core.annotation.ApiObjectField;

@ApiObject
public class City extends Location {

        @ApiObjectField
        private Long id;

        @ApiObjectField(description = "The name of the city")
        private String name;

}

Notes:

The resulting object name in this case will be city (lowercase of class name). If you want to override it, just specify a custom name in the name property of the annotation
Not writing a description for fields will result in a hint in the documentation (and in an informative message in the JSONDoc UI)

Documenting objects that won't be shown but will be considered in building documentation

Superclasses are not always needed from an API user perspective. They are still needed to build an effective documentation though. Here is how to do it:

package org.jsondoc.sample.pojo;

import org.jsondoc.core.annotation.ApiObject;
import org.jsondoc.core.annotation.ApiObjectField;

@ApiObject(show = false)
public class Location {

        @ApiObjectField(description = "The population of the location")
        private Integer population;

        @ApiObjectField(description = "The square km of the location")
        private Integer squarekm;

}

Notes:

The object is annotated with show = false, indicating that this object will take part to the documentation build process, but it will not be shown as a stadalone object in the resulting documentation

Hibernate validator intergration

If JSONDoc finds Hibernate validator libraries on the classpath, it will trigger the scan for its annotations put on objects' fields. It will then extract data from them and use them to display validation rules in the JSONDoc UI. Currently JSONDoc supports these Hibernate validator annotations:

AssertFalse
AssertTrue
NotNull
Null
Size
NotBlank
NotEmpty
Length
Range
DecimalMax
DecimalMin
Future
Past
Digits
Max
Min
Pattern
Email
URL
CreditCardNumber

JSONDoc
easily generate docs and playground for your RESTful API

Contacts

Documenting objects

Documenting objects that won't be shown but will be considered in building documentation

Hibernate validator intergration

JSONDoc easily generate docs and playground for your RESTful API

Contacts

Documenting objects

Documenting objects that won't be shown but will be considered in building documentation

Hibernate validator intergration

JSONDoc
easily generate docs and playground for your RESTful API