001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.jsonschema.annotation; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023 024import org.apache.juneau.*; 025import org.apache.juneau.annotation.*; 026import org.apache.juneau.collections.*; 027import org.apache.juneau.json.*; 028import org.apache.juneau.jsonschema.*; 029import org.apache.juneau.parser.*; 030 031/** 032 * Annotation for specifying config properties defined in {@link JsonSchemaGenerator}. 033 * 034 * <p> 035 * Used primarily for specifying bean configuration properties on REST classes and methods. 036 * 037 * <h5 class='section'>See Also:</h5><ul> 038 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JsonSchemaDetails">JSON-Schema Support</a> 039 * </ul> 040 */ 041@Target({TYPE,METHOD}) 042@Retention(RUNTIME) 043@Inherited 044@ContextApply(JsonSchemaConfigAnnotation.Apply.class) 045public @interface JsonSchemaConfig { 046 047 /** 048 * Optional rank for this config. 049 * 050 * <p> 051 * Can be used to override default ordering and application of config annotations. 052 * 053 * @return The annotation value. 054 */ 055 int rank() default 0; 056 057 //------------------------------------------------------------------------------------------------------------------- 058 // JsonSchemaGenerator 059 //------------------------------------------------------------------------------------------------------------------- 060 061 /** 062 * Add descriptions to types. 063 * 064 * <p> 065 * Identifies which categories of types that descriptions should be automatically added to generated schemas. 066 * 067 * <p> 068 * The description is the result of calling {@link ClassMeta#getFullName()}. 069 * 070 * <h5 class='section'>Notes:</h5><ul> 071 * <li class='note'> 072 * The format is a comma-delimited list of any of the following values: 073 * <ul class='doctree'> 074 * <li><js>"BEAN"</js> 075 * <li><js>"COLLECTION"</js> 076 * <li><js>"ARRAY"</js> 077 * <li><js>"MAP"</js> 078 * <li><js>"STRING"</js> 079 * <li><js>"NUMBER"</js> 080 * <li><js>"BOOLEAN"</js> 081 * <li><js>"ANY"</js> 082 * <li><js>"OTHER"</js> 083 * </ul> 084 * <li class='note'> 085 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 086 * </ul> 087 * 088 * <h5 class='section'>See Also:</h5><ul> 089 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#addDescriptionsTo(TypeCategory...)} 090 * </ul> 091 * 092 * @return The annotation value. 093 */ 094 String addDescriptionsTo() default ""; 095 096 /** 097 * Add examples. 098 * 099 * <p> 100 * Identifies which categories of types that examples should be automatically added to generated schemas. 101 * <p> 102 * The examples come from calling {@link ClassMeta#getExample(BeanSession,JsonParserSession)} which in turn gets examples 103 * from the following: 104 * <ul class='javatree'> 105 * <li class='ja'>{@link Example} 106 * <li class='ja'>{@link Marshalled#example() Marshalled(example)} 107 * </ul> 108 * 109 * <h5 class='section'>Notes:</h5><ul> 110 * <li class='note'> 111 * The format is a comma-delimited list of any of the following values: 112 * <ul class='doctree'> 113 * <li><js>"BEAN"</js> 114 * <li><js>"COLLECTION"</js> 115 * <li><js>"ARRAY"</js> 116 * <li><js>"MAP"</js> 117 * <li><js>"STRING"</js> 118 * <li><js>"NUMBER"</js> 119 * <li><js>"BOOLEAN"</js> 120 * <li><js>"ANY"</js> 121 * <li><js>"OTHER"</js> 122 * </ul> 123 * <li class='note'> 124 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 125 * </ul> 126 * 127 * <h5 class='section'>See Also:</h5><ul> 128 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#addDescriptionsTo(TypeCategory...)} 129 * </ul> 130 * 131 * @return The annotation value. 132 */ 133 String addExamplesTo() default ""; 134 135 /** 136 * Allow nested descriptions. 137 * 138 * <p> 139 * Identifies whether nested descriptions are allowed in schema definitions. 140 * 141 * <ul class='values'> 142 * <li><js>"true"</js> 143 * <li><js>"false"</js> (default) 144 * </ul> 145 * 146 * <h5 class='section'>Notes:</h5><ul> 147 * <li class='note'> 148 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 149 * </ul> 150 * 151 * <h5 class='section'>See Also:</h5><ul> 152 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#allowNestedDescriptions()} 153 * </ul> 154 * 155 * @return The annotation value. 156 */ 157 String allowNestedDescriptions() default ""; 158 159 /** 160 * Allow nested examples. 161 * 162 * <p> 163 * Identifies whether nested examples are allowed in schema definitions. 164 * 165 * <ul class='values'> 166 * <li><js>"true"</js> 167 * <li><js>"false"</js> (default) 168 * </ul> 169 * 170 * <h5 class='section'>Notes:</h5><ul> 171 * <li class='note'> 172 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 173 * </ul> 174 * 175 * <h5 class='section'>See Also:</h5><ul> 176 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#allowNestedExamples()} 177 * </ul> 178 * 179 * @return The annotation value. 180 */ 181 String allowNestedExamples() default ""; 182 183 /** 184 * Bean schema definition mapper. 185 * 186 * <p> 187 * Interface to use for converting Bean classes to definition IDs and URIs. 188 * 189 * <p> 190 * Used primarily for defining common definition sections for beans in Swagger JSON. 191 * 192 * <h5 class='section'>Notes:</h5><ul> 193 * <li class='note'> 194 * This setting is ignored if {@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()} is not enabled. 195 * </ul> 196 * 197 * <h5 class='section'>See Also:</h5><ul> 198 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#beanDefMapper(Class)} 199 * </ul> 200 * 201 * @return The annotation value. 202 */ 203 Class<? extends BeanDefMapper> beanDefMapper() default BeanDefMapper.Void.class; 204 205 /** 206 * Ignore types from schema definitions. 207 * 208 * <p> 209 * Defines class name patterns that should be ignored when generating schema definitions in the generated 210 * Swagger documentation. 211 * 212 * <h5 class='section'>Notes:</h5><ul> 213 * <li class='note'> 214 * Format: Comma-delimited list of patterns 215 * <li class='note'> 216 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 217 * </ul> 218 * 219 * <h5 class='section'>See Also:</h5><ul> 220 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#ignoreTypes(String...)} 221 * </ul> 222 * 223 * @return The annotation value. 224 */ 225 String ignoreTypes() default ""; 226 227 /** 228 * Use bean definitions. 229 * 230 * <p> 231 * When enabled, schemas on beans will be serialized as the following: 232 * <p class='bjson'> 233 * { 234 * type: <js>'object'</js>, 235 * <js>'$ref'</js>: <js>'#/definitions/TypeId'</js> 236 * } 237 * </p> 238 * 239 * <p> 240 * The definitions can then be retrieved from the session using {@link JsonSchemaGeneratorSession#getBeanDefs()}. 241 * 242 * <p> 243 * Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, JsonMap)}. 244 * 245 * <ul class='values'> 246 * <li><js>"true"</js> 247 * <li><js>"false"</js> (default) 248 * </ul> 249 * 250 * <h5 class='section'>Notes:</h5><ul> 251 * <li class='note'> 252 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 253 * </ul> 254 * 255 * <h5 class='section'>See Also:</h5><ul> 256 * <li class='jm'>{@link org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()} 257 * </ul> 258 * 259 * @return The annotation value. 260 */ 261 String useBeanDefs() default ""; 262 263 //----------------------------------------------------------------------------------------------------------------- 264 // BeanTraverseContext 265 //----------------------------------------------------------------------------------------------------------------- 266 267 /** 268 * Automatically detect POJO recursions. 269 * 270 * <p> 271 * Specifies that recursions should be checked for during traversal. 272 * 273 * <p> 274 * Recursions can occur when traversing models that aren't true trees but rather contain loops. 275 * <br>In general, unchecked recursions cause stack-overflow-errors. 276 * <br>These show up as {@link ParseException ParseExceptions} with the message <js>"Depth too deep. Stack overflow occurred."</js>. 277 * 278 * <p> 279 * The behavior when recursions are detected depends on the value for {@link org.apache.juneau.BeanTraverseContext.Builder#ignoreRecursions()}. 280 * 281 * <p> 282 * For example, if a model contains the links A->B->C->A, then the JSON generated will look like 283 * the following when <jsf>BEANTRAVERSE_ignoreRecursions</jsf> is <jk>true</jk>... 284 * 285 * <p class='bjson'> 286 * {A:{B:{C:<jk>null</jk>}}} 287 * </p> 288 * 289 * <ul class='values'> 290 * <li><js>"true"</js> 291 * <li><js>"false"</js> (default) 292 * </ul> 293 * 294 * <h5 class='section'>Notes:</h5><ul> 295 * <li class='warn'> 296 * Checking for recursion can cause a small performance penalty. 297 * <li class='note'> 298 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 299 * </ul> 300 * 301 * <h5 class='section'>See Also:</h5><ul> 302 * <li class='jm'>{@link org.apache.juneau.BeanTraverseContext.Builder#detectRecursions()} 303 * </ul> 304 * 305 * @return The annotation value. 306 */ 307 String detectRecursions() default ""; 308 309 /** 310 * Ignore recursion errors. 311 * 312 * <p> 313 * Used in conjunction with {@link org.apache.juneau.BeanTraverseContext.Builder#detectRecursions()}. 314 * <br>Setting is ignored if <jsf>BEANTRAVERSE_detectRecursions</jsf> is <js>"false"</js>. 315 * 316 * <p> 317 * If <js>"true"</js>, when we encounter the same object when traversing a tree, we set the value to <jk>null</jk>. 318 * <br>Otherwise, a {@link BeanRecursionException} is thrown with the message <js>"Recursion occurred, stack=..."</js>. 319 * 320 * <ul class='values'> 321 * <li><js>"true"</js> 322 * <li><js>"false"</js> (default) 323 * </ul> 324 * 325 * <h5 class='section'>Notes:</h5><ul> 326 * <li class='note'> 327 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 328 * </ul> 329 * 330 * <h5 class='section'>See Also:</h5><ul> 331 * <li class='jm'>{@link org.apache.juneau.BeanTraverseContext.Builder#ignoreRecursions()} 332 * </ul> 333 * 334 * @return The annotation value. 335 */ 336 String ignoreRecursions() default ""; 337 338 /** 339 * Initial depth. 340 * 341 * <p> 342 * The initial indentation level at the root. 343 * <br>Useful when constructing document fragments that need to be indented at a certain level. 344 * 345 * <h5 class='section'>Notes:</h5><ul> 346 * <li class='note'> 347 * Format: integer 348 * <li class='note'> 349 * Default value: <js>"0"</js> 350 * <li class='note'> 351 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 352 * </ul> 353 * 354 * <h5 class='section'>See Also:</h5><ul> 355 * <li class='jm'>{@link org.apache.juneau.BeanTraverseContext.Builder#initialDepth(int)} 356 * </ul> 357 * 358 * @return The annotation value. 359 */ 360 String initialDepth() default ""; 361 362 /** 363 * Max traversal depth. 364 * 365 * <p> 366 * Abort traversal if specified depth is reached in the POJO tree. 367 * <br>If this depth is exceeded, an exception is thrown. 368 * 369 * <h5 class='section'>Notes:</h5><ul> 370 * <li class='note'> 371 * Format: integer 372 * <li class='note'> 373 * Default value: <js>"100"</js> 374 * <li class='note'> 375 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/DefaultVarResolver">VarResolver.DEFAULT</a> (e.g. <js>"$C{myConfigVar}"</js>). 376 * </ul> 377 * 378 * <h5 class='section'>See Also:</h5><ul> 379 * <li class='jm'>{@link org.apache.juneau.BeanTraverseContext.Builder#maxDepth(int)} 380 * </ul> 381 * 382 * @return The annotation value. 383 */ 384 String maxDepth() default ""; 385}