| // *************************************************************************************************************************** |
| // * 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.jsonschema.*; |
| |
| /** |
| * Annotation for specifying config properties defined in {@link JsonSchemaGenerator}. |
| * |
| * <p> |
| * Used primarily for specifying bean configuration properties on REST classes and methods. |
| */ |
| @Documented |
| @Target({TYPE,METHOD}) |
| @Retention(RUNTIME) |
| @Inherited |
| @PropertyStoreApply(JsonSchemaConfigApply.class) |
| public @interface JsonSchemaConfig { |
| |
| /** |
| * Optional rank for this config. |
| * |
| * <p> |
| * Can be used to override default ordering and application of config annotations. |
| */ |
| int rank() default 0; |
| |
| //------------------------------------------------------------------------------------------------------------------- |
| // JsonSchemaGenerator |
| //------------------------------------------------------------------------------------------------------------------- |
| |
| /** |
| * Configuration property: Add descriptions to types. |
| * |
| * <p> |
| * Identifies which categories of types that descriptions should be automatically added to generated schemas. |
| * |
| * <p> |
| * The description is the result of calling {@link ClassMeta#getFullName()}. |
| * |
| * <ul class='notes'> |
| * <li> |
| * The format is a comma-delimited list of any of the following values: |
| * <ul class='doctree'> |
| * <li><js>"BEAN"</js> |
| * <li><js>"COLLECTION"</js> |
| * <li><js>"ARRAY"</js> |
| * <li><js>"MAP"</js> |
| * <li><js>"STRING"</js> |
| * <li><js>"NUMBER"</js> |
| * <li><js>"BOOLEAN"</js> |
| * <li><js>"ANY"</js> |
| * <li><js>"OTHER"</js> |
| * </ul> |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} |
| * </ul> |
| */ |
| String addDescriptionsTo() default ""; |
| |
| /** |
| * Configuration property: Add examples. |
| * |
| * <p> |
| * Identifies which categories of types that examples should be automatically added to generated schemas. |
| * <p> |
| * The examples come from calling {@link ClassMeta#getExample(BeanSession)} which in turn gets examples |
| * from the following: |
| * <ul class='javatree'> |
| * <li class='ja'>{@link Example} |
| * <li class='jf'>{@link BeanContext#BEAN_examples} |
| * </ul> |
| * |
| * <ul class='notes'> |
| * <li> |
| * The format is a comma-delimited list of any of the following values: |
| * <ul class='doctree'> |
| * <li><js>"BEAN"</js> |
| * <li><js>"COLLECTION"</js> |
| * <li><js>"ARRAY"</js> |
| * <li><js>"MAP"</js> |
| * <li><js>"STRING"</js> |
| * <li><js>"NUMBER"</js> |
| * <li><js>"BOOLEAN"</js> |
| * <li><js>"ANY"</js> |
| * <li><js>"OTHER"</js> |
| * </ul> |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} |
| * </ul> |
| */ |
| String addExamplesTo() default ""; |
| |
| /** |
| * Configuration property: Allow nested descriptions. |
| * |
| * <p> |
| * Identifies whether nested descriptions are allowed in schema definitions. |
| * |
| * <ul class='notes'> |
| * <li> |
| * Possible values: |
| * <ul> |
| * <li><js>"true"</js> |
| * <li><js>"false"</js> (default) |
| * </ul> |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedDescriptions.b"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedDescriptions} |
| * </ul> |
| */ |
| String allowNestedDescriptions() default ""; |
| |
| /** |
| * Configuration property: Allow nested examples. |
| * |
| * <p> |
| * Identifies whether nested examples are allowed in schema definitions. |
| * |
| * <ul class='notes'> |
| * <li> |
| * Possible values: |
| * <ul> |
| * <li><js>"true"</js> |
| * <li><js>"false"</js> (default) |
| * </ul> |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedExamples.b"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples} |
| * </ul> |
| */ |
| String allowNestedExamples() default ""; |
| |
| /** |
| * Dynamically applies {@link Schema @Schema} annotations to specified classes/methods/fields. |
| * |
| * <p> |
| * Provides an alternate approach for applying annotations using {@link Schema#on() @Schema.on} to specify the names |
| * to apply the annotation to. |
| * |
| * <ul class='seealso'> |
| * <li class='link'>{@doc juneau-marshall.DynamicallyAppliedAnnotations} |
| * </ul> |
| */ |
| Schema[] applySchema() default {}; |
| |
| /** |
| * Configuration property: Bean schema definition mapper. |
| * |
| * <p> |
| * Interface to use for converting Bean classes to definition IDs and URIs. |
| * |
| * <p> |
| * Used primarily for defining common definition sections for beans in Swagger JSON. |
| * |
| * <ul class='notes'> |
| * <li> |
| * This setting is ignored if {@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} is not enabled. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_beanDefMapper} |
| * </ul> |
| */ |
| Class<? extends BeanDefMapper> beanDefMapper() default BeanDefMapper.Null.class; |
| |
| /** |
| * Configuration property: Default schemas. |
| * |
| * <p> |
| * Allows you to override or provide custom schema information for particular class types. |
| * |
| * <ul class='notes'> |
| * <li> |
| * Keys are the class. |
| * <br>Values are Simple-JSON objects. |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.defaultSchema.smo"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_defaultSchemas} |
| * </ul> |
| */ |
| CS[] defaultSchemas() default {}; |
| |
| /** |
| * Configuration property: Ignore types from schema definitions. |
| * |
| * <p> |
| * Defines class name patterns that should be ignored when generating schema definitions in the generated |
| * Swagger documentation. |
| * |
| * <ul class='notes'> |
| * <li> |
| * Format: Comma-delimited list of patterns |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.ignoreTypes.s"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_ignoreTypes} |
| * </ul> |
| */ |
| String ignoreTypes() default ""; |
| |
| /** |
| * Configuration property: Use bean definitions. |
| * |
| * <p> |
| * When enabled, schemas on beans will be serialized as the following: |
| * <p class='bcode w800'> |
| * { |
| * type: <js>'object'</js>, |
| * <js>'$ref'</js>: <js>'#/definitions/TypeId'</js> |
| * } |
| * </p> |
| * |
| * <p> |
| * The definitions can then be retrieved from the session using {@link JsonSchemaGeneratorSession#getBeanDefs()}. |
| * |
| * <p> |
| * Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, ObjectMap)}. |
| * |
| * <ul class='notes'> |
| * <li> |
| * Possible values: |
| * <ul> |
| * <li><js>"true"</js> |
| * <li><js>"false"</js> (default) |
| * </ul> |
| * <li> |
| * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). |
| * <li> |
| * A default global value can be set via the system property <js>"JsonSchemaGenerator.useBeanDefs.b"</js>. |
| * </ul> |
| * |
| * <ul class='seealso'> |
| * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} |
| * </ul> |
| */ |
| String useBeanDefs() default ""; |
| } |