Introduction, Motivation
With the existence of the JAXB architecture and API, Enunciate is able to automatically detect and document XML-based models in your API with little or no extra assistance. Unfortunately, there is no such common architecture, model, nor declarative mechanisms (e.g. annotations) for JSON models in Java. There are various options, including Gson, json-lib, and jackson, but Enunciate could use a general way to know what your JSON model is. This is especially true when any of those options provide no declarative link between the model and serialization process. So, in the absence of serialization-specific Enunciate modules like gson, (which may appear in the future), the following annotations can be used to inform Enunciate of your JSON-serializable models.
All of these annotations are located in package org.codehaus.enunciate.json in artifact org.codehaus.enunciate:enunciate-core-annotations.
Enunciate JSON Annotations
@JsonRootType
This annotation causes Enunciate to add the type as a JSON root type. Root types are those that can be the primary type of a payload. If excludeUnreferencedClasses is true in the enunciate configuration, then the type must be used as a JAX-RS entity type to be added to the model. The default name of a root type is the simple name (i.e. unqualified class name) of the Java type. This can be overridden with @JsonName.
@JsonType
This annotation causes Enunciate to add the type as a JSON type. If excludeUnreferencedClasses is true in the enunciate configuration, then the type must be referenced by a JAX-RS entity type to be added to the model. The default name of a type is the simple name (i.e. unqualified class name) of the Java type. This can be overridden with @JsonName.
@JsonProperty
Used to indicate a property on a JSON type. Currently this isn't required as properties are automatically detected on types (TODO add opt-in mode on per-type basis). The default name of a property is the JavaBean property name.
@JsonName
Used to override the default JSON type-name of the annotated Java type or property.
@JsonIgnore
This annotation causes Enunciate to ignore a property on an otherwise documented JSON type.
@JsonSchema
Used on a Java package to give a specific schema ID to any JSON types detected within it. If a specific schema ID is used on multiple Java packages, then they are composed into a larger schema. The default ID of a schema is the Java package name.
@JsonTypeMappings, @JsonTypeMapping
Package-level annotations used to directly specify mappings from Java to JSON types. This is normally used for (but not limited to) the following purposes.
- Java type is being handled in custom adapter code or whose JSON structure is otherwise not exposed in a project-specific declaration.
- Java type comes from a 3rd-party library and so annotations can not be applied to it.
Type/Property-level mapping annotations
Coming soon!
Arrays and Collections
When an array or collection is encountered, Enunciate will determine the component type and document it as a JSON list.
Maps
Coming soon!
Enunciate Jackson-JAXB Detection
Coming soon!