001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.jsonschema.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.*; 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.jsonschema.*; 023 024/** 025 * Annotation for specifying config properties defined in {@link JsonSchemaGenerator}. 026 * 027 * <p> 028 * Used primarily for specifying bean configuration properties on REST classes and methods. 029 */ 030@Documented 031@Target({TYPE,METHOD}) 032@Retention(RUNTIME) 033@Inherited 034@PropertyStoreApply(JsonSchemaConfigApply.class) 035public @interface JsonSchemaConfig { 036 037 //------------------------------------------------------------------------------------------------------------------- 038 // JsonSchemaGenerator 039 //------------------------------------------------------------------------------------------------------------------- 040 041 /** 042 * Configuration property: Add descriptions to types. 043 * 044 * <p> 045 * Identifies which categories of types that descriptions should be automatically added to generated schemas. 046 * 047 * <p> 048 * The description is the result of calling {@link ClassMeta#getFullName()}. 049 * 050 * <ul class='notes'> 051 * <li> 052 * The format is a comma-delimited list of any of the following values: 053 * <ul class='doctree'> 054 * <li><js>"BEAN"</js> 055 * <li><js>"COLLECTION"</js> 056 * <li><js>"ARRAY"</js> 057 * <li><js>"MAP"</js> 058 * <li><js>"STRING"</js> 059 * <li><js>"NUMBER"</js> 060 * <li><js>"BOOLEAN"</js> 061 * <li><js>"ANY"</js> 062 * <li><js>"OTHER"</js> 063 * </ul> 064 * <li> 065 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 066 * <li> 067 * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. 068 * </ul> 069 * 070 * <ul class='seealso'> 071 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} 072 * </ul> 073 */ 074 String addDescriptionsTo() default ""; 075 076 /** 077 * Configuration property: Add examples. 078 * 079 * <p> 080 * Identifies which categories of types that examples should be automatically added to generated schemas. 081 * <p> 082 * The examples come from calling {@link ClassMeta#getExample(BeanSession)} which in turn gets examples 083 * from the following: 084 * <ul class='javatree'> 085 * <li class='ja'>{@link Example} 086 * <li class='jf'>{@link BeanContext#BEAN_examples} 087 * </ul> 088 * 089 * <ul class='notes'> 090 * <li> 091 * The format is a comma-delimited list of any of the following values: 092 * <ul class='doctree'> 093 * <li><js>"BEAN"</js> 094 * <li><js>"COLLECTION"</js> 095 * <li><js>"ARRAY"</js> 096 * <li><js>"MAP"</js> 097 * <li><js>"STRING"</js> 098 * <li><js>"NUMBER"</js> 099 * <li><js>"BOOLEAN"</js> 100 * <li><js>"ANY"</js> 101 * <li><js>"OTHER"</js> 102 * </ul> 103 * <li> 104 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 105 * <li> 106 * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. 107 * </ul> 108 * 109 * <ul class='seealso'> 110 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} 111 * </ul> 112 */ 113 String addExamplesTo() default ""; 114 115 /** 116 * Configuration property: Allow nested descriptions. 117 * 118 * <p> 119 * Identifies whether nested descriptions are allowed in schema definitions. 120 * 121 * <ul class='notes'> 122 * <li> 123 * Possible values: 124 * <ul> 125 * <li><js>"true"</js> 126 * <li><js>"false"</js> (default) 127 * </ul> 128 * <li> 129 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 130 * <li> 131 * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedDescriptions.b"</js>. 132 * </ul> 133 * 134 * <ul class='seealso'> 135 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedDescriptions} 136 * </ul> 137 */ 138 String allowNestedDescriptions() default ""; 139 140 /** 141 * Configuration property: Allow nested examples. 142 * 143 * <p> 144 * Identifies whether nested examples are allowed in schema definitions. 145 * 146 * <ul class='notes'> 147 * <li> 148 * Possible values: 149 * <ul> 150 * <li><js>"true"</js> 151 * <li><js>"false"</js> (default) 152 * </ul> 153 * <li> 154 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 155 * <li> 156 * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedExamples.b"</js>. 157 * </ul> 158 * 159 * <ul class='seealso'> 160 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples} 161 * </ul> 162 */ 163 String allowNestedExamples() default ""; 164 165 /** 166 * Configuration property: Bean schema definition mapper. 167 * 168 * <p> 169 * Interface to use for converting Bean classes to definition IDs and URIs. 170 * 171 * <p> 172 * Used primarily for defining common definition sections for beans in Swagger JSON. 173 * 174 * <ul class='notes'> 175 * <li> 176 * This setting is ignored if {@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} is not enabled. 177 * </ul> 178 * 179 * <ul class='seealso'> 180 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_beanDefMapper} 181 * </ul> 182 */ 183 Class<? extends BeanDefMapper> beanDefMapper() default BeanDefMapper.Null.class; 184 185 /** 186 * Configuration property: Default schemas. 187 * 188 * <p> 189 * Allows you to override or provide custom schema information for particular class types. 190 * 191 * <ul class='notes'> 192 * <li> 193 * Keys are the class. 194 * <br>Values are Simple-JSON objects. 195 * <li> 196 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 197 * <li> 198 * A default global value can be set via the system property <js>"JsonSchemaGenerator.defaultSchema.smo"</js>. 199 * </ul> 200 * 201 * <ul class='seealso'> 202 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_defaultSchemas} 203 * </ul> 204 */ 205 CS[] defaultSchemas() default {}; 206 207 /** 208 * Configuration property: Ignore types from schema definitions. 209 * 210 * <p> 211 * Defines class name patterns that should be ignored when generating schema definitions in the generated 212 * Swagger documentation. 213 * 214 * <ul class='notes'> 215 * Format: Comma-delimited list of patterns 216 * <li> 217 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 218 * <li> 219 * A default global value can be set via the system property <js>"JsonSchemaGenerator.ignoreTypes.s"</js>. 220 * </ul> 221 * 222 * <ul class='seealso'> 223 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_ignoreTypes} 224 * </ul> 225 */ 226 String ignoreTypes() default ""; 227 228 /** 229 * Configuration property: Use bean definitions. 230 * 231 * <p> 232 * When enabled, schemas on beans will be serialized as the following: 233 * <p class='bcode w800'> 234 * { 235 * type: <js>'object'</js>, 236 * <js>'$ref'</js>: <js>'#/definitions/TypeId'</js> 237 * } 238 * </p> 239 * 240 * <p> 241 * The definitions can then be retrieved from the session using {@link JsonSchemaGeneratorSession#getBeanDefs()}. 242 * 243 * <p> 244 * Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, ObjectMap)}. 245 * 246 * <ul class='notes'> 247 * <li> 248 * Possible values: 249 * <ul> 250 * <li><js>"true"</js> 251 * <li><js>"false"</js> (default) 252 * </ul> 253 * <li> 254 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 255 * <li> 256 * A default global value can be set via the system property <js>"JsonSchemaGenerator.useBeanDefs.b"</js>. 257 * </ul> 258 * 259 * <ul class='seealso'> 260 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} 261 * </ul> 262 */ 263 String useBeanDefs() default ""; 264}