org.apache.juneau.jsonschema.annotation.JsonSchemaConfig Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.jsonschema.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.collections.*;
import org.apache.juneau.json.*;
import org.apache.juneau.jsonschema.*;
import org.apache.juneau.parser.*;
/**
* Annotation for specifying config properties defined in {@link JsonSchemaGenerator}.
*
*
* Used primarily for specifying bean configuration properties on REST classes and methods.
*
*
See Also:
*/
@Target({TYPE,METHOD})
@Retention(RUNTIME)
@Inherited
@ContextApply(JsonSchemaConfigAnnotation.Apply.class)
public @interface JsonSchemaConfig {
/**
* Optional rank for this config.
*
*
* Can be used to override default ordering and application of config annotations.
*
* @return The annotation value.
*/
int rank() default 0;
//-------------------------------------------------------------------------------------------------------------------
// JsonSchemaGenerator
//-------------------------------------------------------------------------------------------------------------------
/**
* 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 {@link 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:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#addDescriptionsTo(TypeCategory...)}
*
*
* @return The annotation value.
*/
String addDescriptionsTo() default "";
/**
* Add examples.
*
*
* Identifies which categories of types that examples should be automatically added to generated schemas.
*
* The examples come from calling {@link ClassMeta#getExample(BeanSession,JsonParserSession)} which in turn gets examples
* from the following:
*
* - {@link Example}
*
- {@link Marshalled#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:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#addDescriptionsTo(TypeCategory...)}
*
*
* @return The annotation value.
*/
String addExamplesTo() default "";
/**
* 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:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#allowNestedDescriptions()}
*
*
* @return The annotation value.
*/
String allowNestedDescriptions() default "";
/**
* 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:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#allowNestedExamples()}
*
*
* @return The annotation value.
*/
String allowNestedExamples() default "";
/**
* 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 {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()} is not enabled.
*
*
* See Also:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#beanDefMapper(Class)}
*
*
* @return The annotation value.
*/
Class beanDefMapper() default BeanDefMapper.Void.class;
/**
* 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:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#ignoreTypes(String...)}
*
*
* @return The annotation value.
*/
String ignoreTypes() default "";
/**
* 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 {@link JsonSchemaGeneratorSession#getBeanDefs()}.
*
*
* Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, JsonMap)}.
*
*
* "true"
* "false" (default)
*
*
* Notes:
* -
* Supports VarResolver.DEFAULT (e.g.
"$C{myConfigVar}" ).
*
*
* See Also:
* - {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()}
*
*
* @return The annotation value.
*/
String useBeanDefs() default "";
//-----------------------------------------------------------------------------------------------------------------
// BeanTraverseContext
//-----------------------------------------------------------------------------------------------------------------
/**
* 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 {@link ParseException ParseExceptions} with the message "Depth too deep. Stack overflow occurred." .
*
*
* The behavior when recursions are detected depends on the value for {@link org.apache.juneau.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:
* - {@link org.apache.juneau.BeanTraverseContext.Builder#detectRecursions()}
*
*
* @return The annotation value.
*/
String detectRecursions() default "";
/**
* Ignore recursion errors.
*
*
* Used in conjunction with {@link org.apache.juneau.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 {@link BeanRecursionException} is thrown with the message "Recursion occurred, stack=..." .
*
*
* "true"
* "false" (default)
*
*
* Notes:
* -
* Supports VarResolver.DEFAULT (e.g.
"$C{myConfigVar}" ).
*
*
* See Also:
* - {@link org.apache.juneau.BeanTraverseContext.Builder#ignoreRecursions()}
*
*
* @return The annotation value.
*/
String ignoreRecursions() default "";
/**
* 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:
* - {@link org.apache.juneau.BeanTraverseContext.Builder#initialDepth(int)}
*
*
* @return The annotation value.
*/
String initialDepth() default "";
/**
* 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:
* - {@link org.apache.juneau.BeanTraverseContext.Builder#maxDepth(int)}
*
*
* @return The annotation value.
*/
String maxDepth() default "";
}