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 * Optional rank for this config. 039 * 040 * <p> 041 * Can be used to override default ordering and application of config annotations. 042 */ 043 int rank() default 0; 044 045 //------------------------------------------------------------------------------------------------------------------- 046 // JsonSchemaGenerator 047 //------------------------------------------------------------------------------------------------------------------- 048 049 /** 050 * Configuration property: Add descriptions to types. 051 * 052 * <p> 053 * Identifies which categories of types that descriptions should be automatically added to generated schemas. 054 * 055 * <p> 056 * The description is the result of calling {@link ClassMeta#getFullName()}. 057 * 058 * <ul class='notes'> 059 * <li> 060 * The format is a comma-delimited list of any of the following values: 061 * <ul class='doctree'> 062 * <li><js>"BEAN"</js> 063 * <li><js>"COLLECTION"</js> 064 * <li><js>"ARRAY"</js> 065 * <li><js>"MAP"</js> 066 * <li><js>"STRING"</js> 067 * <li><js>"NUMBER"</js> 068 * <li><js>"BOOLEAN"</js> 069 * <li><js>"ANY"</js> 070 * <li><js>"OTHER"</js> 071 * </ul> 072 * <li> 073 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 074 * <li> 075 * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. 076 * </ul> 077 * 078 * <ul class='seealso'> 079 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} 080 * </ul> 081 */ 082 String addDescriptionsTo() default ""; 083 084 /** 085 * Configuration property: Add examples. 086 * 087 * <p> 088 * Identifies which categories of types that examples should be automatically added to generated schemas. 089 * <p> 090 * The examples come from calling {@link ClassMeta#getExample(BeanSession)} which in turn gets examples 091 * from the following: 092 * <ul class='javatree'> 093 * <li class='ja'>{@link Example} 094 * <li class='jf'>{@link BeanContext#BEAN_examples} 095 * </ul> 096 * 097 * <ul class='notes'> 098 * <li> 099 * The format is a comma-delimited list of any of the following values: 100 * <ul class='doctree'> 101 * <li><js>"BEAN"</js> 102 * <li><js>"COLLECTION"</js> 103 * <li><js>"ARRAY"</js> 104 * <li><js>"MAP"</js> 105 * <li><js>"STRING"</js> 106 * <li><js>"NUMBER"</js> 107 * <li><js>"BOOLEAN"</js> 108 * <li><js>"ANY"</js> 109 * <li><js>"OTHER"</js> 110 * </ul> 111 * <li> 112 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 113 * <li> 114 * A default global value can be set via the system property <js>"JsonSchemaGenerator.addDescriptionsTo.s"</js>. 115 * </ul> 116 * 117 * <ul class='seealso'> 118 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_addDescriptionsTo} 119 * </ul> 120 */ 121 String addExamplesTo() default ""; 122 123 /** 124 * Configuration property: Allow nested descriptions. 125 * 126 * <p> 127 * Identifies whether nested descriptions are allowed in schema definitions. 128 * 129 * <ul class='notes'> 130 * <li> 131 * Possible values: 132 * <ul> 133 * <li><js>"true"</js> 134 * <li><js>"false"</js> (default) 135 * </ul> 136 * <li> 137 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 138 * <li> 139 * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedDescriptions.b"</js>. 140 * </ul> 141 * 142 * <ul class='seealso'> 143 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedDescriptions} 144 * </ul> 145 */ 146 String allowNestedDescriptions() default ""; 147 148 /** 149 * Configuration property: Allow nested examples. 150 * 151 * <p> 152 * Identifies whether nested examples are allowed in schema definitions. 153 * 154 * <ul class='notes'> 155 * <li> 156 * Possible values: 157 * <ul> 158 * <li><js>"true"</js> 159 * <li><js>"false"</js> (default) 160 * </ul> 161 * <li> 162 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 163 * <li> 164 * A default global value can be set via the system property <js>"JsonSchemaGenerator.allowNestedExamples.b"</js>. 165 * </ul> 166 * 167 * <ul class='seealso'> 168 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples} 169 * </ul> 170 */ 171 String allowNestedExamples() default ""; 172 173 /** 174 * Configuration property: Bean schema definition mapper. 175 * 176 * <p> 177 * Interface to use for converting Bean classes to definition IDs and URIs. 178 * 179 * <p> 180 * Used primarily for defining common definition sections for beans in Swagger JSON. 181 * 182 * <ul class='notes'> 183 * <li> 184 * This setting is ignored if {@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} is not enabled. 185 * </ul> 186 * 187 * <ul class='seealso'> 188 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_beanDefMapper} 189 * </ul> 190 */ 191 Class<? extends BeanDefMapper> beanDefMapper() default BeanDefMapper.Null.class; 192 193 /** 194 * Configuration property: Default schemas. 195 * 196 * <p> 197 * Allows you to override or provide custom schema information for particular class types. 198 * 199 * <ul class='notes'> 200 * <li> 201 * Keys are the class. 202 * <br>Values are Simple-JSON objects. 203 * <li> 204 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 205 * <li> 206 * A default global value can be set via the system property <js>"JsonSchemaGenerator.defaultSchema.smo"</js>. 207 * </ul> 208 * 209 * <ul class='seealso'> 210 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_defaultSchemas} 211 * </ul> 212 */ 213 CS[] defaultSchemas() default {}; 214 215 /** 216 * Configuration property: Ignore types from schema definitions. 217 * 218 * <p> 219 * Defines class name patterns that should be ignored when generating schema definitions in the generated 220 * Swagger documentation. 221 * 222 * <ul class='notes'> 223 * <li> 224 * Format: Comma-delimited list of patterns 225 * <li> 226 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 227 * <li> 228 * A default global value can be set via the system property <js>"JsonSchemaGenerator.ignoreTypes.s"</js>. 229 * </ul> 230 * 231 * <ul class='seealso'> 232 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_ignoreTypes} 233 * </ul> 234 */ 235 String ignoreTypes() default ""; 236 237 /** 238 * Configuration property: Use bean definitions. 239 * 240 * <p> 241 * When enabled, schemas on beans will be serialized as the following: 242 * <p class='bcode w800'> 243 * { 244 * type: <js>'object'</js>, 245 * <js>'$ref'</js>: <js>'#/definitions/TypeId'</js> 246 * } 247 * </p> 248 * 249 * <p> 250 * The definitions can then be retrieved from the session using {@link JsonSchemaGeneratorSession#getBeanDefs()}. 251 * 252 * <p> 253 * Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, ObjectMap)}. 254 * 255 * <ul class='notes'> 256 * <li> 257 * Possible values: 258 * <ul> 259 * <li><js>"true"</js> 260 * <li><js>"false"</js> (default) 261 * </ul> 262 * <li> 263 * Supports {@doc DefaultSvlVariables} (e.g. <js>"$C{myConfigVar}"</js>). 264 * <li> 265 * A default global value can be set via the system property <js>"JsonSchemaGenerator.useBeanDefs.b"</js>. 266 * </ul> 267 * 268 * <ul class='seealso'> 269 * <li class='jf'>{@link JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} 270 * </ul> 271 */ 272 String useBeanDefs() default ""; 273}