Package org.apache.juneau.jsonschema.annotation

Annotation Type JsonSchemaConfig

@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
@ContextApply(Apply.class)
public @interface JsonSchemaConfig

Annotation for specifying config properties defined in JsonSchemaGenerator.

Used primarily for specifying bean configuration properties on REST classes and methods.

See Also:

• JSON-Schema Support

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	addDescriptionsTo	Add descriptions to types.
String	addExamplesTo	Add examples.
String	allowNestedDescriptions	Allow nested descriptions.
String	allowNestedExamples	Allow nested examples.
Class<? extends BeanDefMapper>	beanDefMapper	Bean schema definition mapper.
String	detectRecursions	Automatically detect POJO recursions.
String	ignoreRecursions	Ignore recursion errors.
String	ignoreTypes	Ignore types from schema definitions.
String	initialDepth	Initial depth.
String	maxDepth	Max traversal depth.
int	rank	Optional rank for this config.
String	useBeanDefs	Use bean definitions.

Element Details

rank

int rank

Optional rank for this config.

Can be used to override default ordering and application of config annotations.

Returns:

The annotation value.

Default:

0

addDescriptionsTo

String addDescriptionsTo

Add descriptions to types.

Identifies which categories of types that descriptions should be automatically added to generated schemas.

The description is the result of calling ClassMeta.getFullName().

Notes:

• The format is a comma-delimited list of any of the following values:
  • "BEAN"
  • "COLLECTION"
  • "ARRAY"
  • "MAP"
  • "STRING"
  • "NUMBER"
  • "BOOLEAN"
  • "ANY"
  • "OTHER"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.addDescriptionsTo(TypeCategory...)

Returns:

The annotation value.

Default:

""

addExamplesTo

String addExamplesTo

Add examples.

Identifies which categories of types that examples should be automatically added to generated schemas.

The examples come from calling ClassMeta.getExample(BeanSession,JsonParserSession) which in turn gets examples from the following:

• Example
• Marshalled(example)

Notes:

• The format is a comma-delimited list of any of the following values:
  • "BEAN"
  • "COLLECTION"
  • "ARRAY"
  • "MAP"
  • "STRING"
  • "NUMBER"
  • "BOOLEAN"
  • "ANY"
  • "OTHER"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.addDescriptionsTo(TypeCategory...)

Returns:

The annotation value.

Default:

""

allowNestedDescriptions

String allowNestedDescriptions

Allow nested descriptions.

Identifies whether nested descriptions are allowed in schema definitions.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.allowNestedDescriptions()

Returns:

The annotation value.

Default:

""

allowNestedExamples

String allowNestedExamples

Allow nested examples.

Identifies whether nested examples are allowed in schema definitions.

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.allowNestedExamples()

Returns:

The annotation value.

Default:

""

beanDefMapper

Class<? extends BeanDefMapper> beanDefMapper

Bean schema definition mapper.

Interface to use for converting Bean classes to definition IDs and URIs.

Used primarily for defining common definition sections for beans in Swagger JSON.

Notes:

• This setting is ignored if JsonSchemaGenerator.Builder.useBeanDefs() is not enabled.

See Also:

• JsonSchemaGenerator.Builder.beanDefMapper(Class)

Returns:

The annotation value.

Default:

org.apache.juneau.jsonschema.BeanDefMapper.Void.class

ignoreTypes

String ignoreTypes

Ignore types from schema definitions.

Defines class name patterns that should be ignored when generating schema definitions in the generated Swagger documentation.

Notes:

• Format: Comma-delimited list of patterns
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.ignoreTypes(String...)

Returns:

The annotation value.

Default:

""

useBeanDefs

String useBeanDefs

Use bean definitions.

When enabled, schemas on beans will be serialized as the following:

{ type: 'object', '$ref': '#/definitions/TypeId' }

The definitions can then be retrieved from the session using JsonSchemaGeneratorSession.getBeanDefs().

Definitions can also be added programmatically using JsonSchemaGeneratorSession.addBeanDef(String, JsonMap).

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• JsonSchemaGenerator.Builder.useBeanDefs()

Returns:

The annotation value.

Default:

""

detectRecursions

String detectRecursions

Automatically detect POJO recursions.

Specifies that recursions should be checked for during traversal.

Recursions can occur when traversing models that aren't true trees but rather contain loops.
In general, unchecked recursions cause stack-overflow-errors.
These show up as ParseExceptions with the message "Depth too deep. Stack overflow occurred.".

The behavior when recursions are detected depends on the value for BeanTraverseContext.Builder.ignoreRecursions().

For example, if a model contains the links A->B->C->A, then the JSON generated will look like the following when BEANTRAVERSE_ignoreRecursions is true...

{A:{B:{C:null}}}

• "true"
• "false" (default)

Notes:

• Checking for recursion can cause a small performance penalty.
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.detectRecursions()

Returns:

The annotation value.

Default:

""

ignoreRecursions

String ignoreRecursions

Ignore recursion errors.

Used in conjunction with BeanTraverseContext.Builder.detectRecursions().
Setting is ignored if BEANTRAVERSE_detectRecursions is "false".

If "true", when we encounter the same object when traversing a tree, we set the value to null.
Otherwise, a BeanRecursionException is thrown with the message "Recursion occurred, stack=...".

• "true"
• "false" (default)

Notes:

• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.ignoreRecursions()

Returns:

The annotation value.

Default:

""

initialDepth

String initialDepth

Initial depth.

The initial indentation level at the root.
Useful when constructing document fragments that need to be indented at a certain level.

Notes:

• Format: integer
• Default value: "0"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.initialDepth(int)

Returns:

The annotation value.

Default:

""

maxDepth

String maxDepth

Max traversal depth.

Abort traversal if specified depth is reached in the POJO tree.
If this depth is exceeded, an exception is thrown.

Notes:

• Format: integer
• Default value: "100"
• Supports VarResolver.DEFAULT (e.g. "$C{myConfigVar}").

See Also:

• BeanTraverseContext.Builder.maxDepth(int)

Returns:

The annotation value.

Default:

""