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