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.marshall.jsonschema; 018 019import static org.apache.juneau.commons.utils.CollectionUtils.*; 020import static org.apache.juneau.commons.utils.Shorts.*; 021import static org.apache.juneau.commons.utils.StringUtils.*; 022import static org.apache.juneau.commons.utils.SystemUtils.*; 023import static org.apache.juneau.commons.utils.ThrowableUtils.*; 024 025import java.util.*; 026import java.util.concurrent.*; 027import java.util.regex.*; 028 029import org.apache.juneau.commons.bean.*; 030import org.apache.juneau.commons.collections.*; 031import org.apache.juneau.marshall.*; 032import org.apache.juneau.marshall.collections.*; 033import org.apache.juneau.marshall.json.*; 034import org.apache.juneau.marshall.json5.*; 035 036/** 037 * Generates JSON-schema metadata about POJOs. 038 * 039 * <h2 class='section'>Notes:</h2><ul> 040 * <li class='note'>This class is thread safe and reusable. 041 * </ul> 042 * 043 * <h2 class='section'>See Also:</h2><ul> 044 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JsonSchemaDetails">JSON-Schema Support</a> 045 * </ul> 046 */ 047@SuppressWarnings({ 048 "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants 049 "java:S1452" // Builder<?> wildcard return intentional; callers chain via fluent API without needing the concrete type 050}) 051public class JsonSchemaGenerator extends MarshallingTraverseContext implements JsonSchemaMetaProvider { 052 053 /** 054 * Builder class. 055 */ 056 public static class Builder extends MarshallingTraverseContext.Builder<Builder> { 057 058 private static final Cache<HashKey,JsonSchemaGenerator> CACHE = Cache.of(HashKey.class, JsonSchemaGenerator.class).build(); 059 060 protected final JsonParser.Builder<?> jsonParserBuilder; 061 protected final JsonSerializer.Builder<?> jsonSerializerBuilder; 062 063 private boolean allowNestedDescriptions; 064 private boolean allowNestedExamples; 065 private boolean useBeanDefs; 066 private Class<? extends MarshallingDefMapper> beanDefMapper; 067 private SortedSet<TypeCategory> addDescriptionsTo; 068 private SortedSet<TypeCategory> addExamplesTo; 069 private SortedSet<String> ignoreTypes; 070 071 /** 072 * Constructor, default settings. 073 */ 074 protected Builder() { 075 MarshallingContext.Builder bc = marshallingContext(); 076 jsonSerializerBuilder = JsonSerializer.create().marshallingContext(bc); 077 jsonParserBuilder = Json5Parser.create().marshallingContext(bc); 078 registerBuilders(jsonSerializerBuilder, jsonParserBuilder); 079 addDescriptionsTo = null; 080 addExamplesTo = null; 081 allowNestedDescriptions = env("JsonSchemaGenerator.allowNestedDescriptions", false); 082 allowNestedExamples = env("JsonSchemaGenerator.allowNestedExamples", false); 083 useBeanDefs = env("JsonSchemaGenerator.useBeanDefs", false); 084 beanDefMapper = BasicBeanDefMapper.class; 085 ignoreTypes = null; 086 } 087 088 /** 089 * Copy constructor. 090 * 091 * @param copyFrom The builder to copy from. 092 * <br>Cannot be <jk>null</jk>. 093 */ 094 protected Builder(Builder copyFrom) { 095 super(reqnn("copyFrom", copyFrom)); 096 MarshallingContext.Builder bc = marshallingContext(); 097 jsonSerializerBuilder = copyFrom.jsonSerializerBuilder.copy().marshallingContext(bc); 098 jsonParserBuilder = copyFrom.jsonParserBuilder.copy().marshallingContext(bc); 099 registerBuilders(jsonSerializerBuilder, jsonParserBuilder); 100 addDescriptionsTo = copyFrom.addDescriptionsTo == null ? null : new TreeSet<>(copyFrom.addDescriptionsTo); 101 addExamplesTo = copyFrom.addExamplesTo == null ? null : new TreeSet<>(copyFrom.addExamplesTo); 102 allowNestedDescriptions = copyFrom.allowNestedDescriptions; 103 allowNestedExamples = copyFrom.allowNestedExamples; 104 beanDefMapper = copyFrom.beanDefMapper; 105 ignoreTypes = copyFrom.ignoreTypes == null ? null : new TreeSet<>(copyFrom.ignoreTypes); 106 useBeanDefs = copyFrom.useBeanDefs; 107 } 108 109 /** 110 * Copy constructor. 111 * 112 * @param copyFrom The bean to copy from. 113 * <br>Cannot be <jk>null</jk>. 114 */ 115 protected Builder(JsonSchemaGenerator copyFrom) { 116 super(reqnn("copyFrom", copyFrom)); 117 MarshallingContext.Builder bc = marshallingContext(); 118 jsonSerializerBuilder = copyFrom.jsonSerializer.copy().marshallingContext(bc); 119 jsonParserBuilder = copyFrom.jsonParser.copy().marshallingContext(bc); 120 registerBuilders(jsonSerializerBuilder, jsonParserBuilder); 121 addDescriptionsTo = copyFrom.addDescriptionsTo.isEmpty() ? null : new TreeSet<>(copyFrom.addDescriptionsTo); 122 addExamplesTo = copyFrom.addExamplesTo.isEmpty() ? null : new TreeSet<>(copyFrom.addExamplesTo); 123 allowNestedDescriptions = copyFrom.allowNestedDescriptions; 124 allowNestedExamples = copyFrom.allowNestedExamples; 125 beanDefMapper = copyFrom.beanDefMapper; 126 ignoreTypes = copyFrom.ignoreTypes.isEmpty() ? null : new TreeSet<>(copyFrom.ignoreTypes); 127 useBeanDefs = copyFrom.useBeanDefs; 128 } 129 130 /** 131 * Add descriptions. 132 * 133 * <p> 134 * Identifies which categories of types that descriptions should be automatically added to generated schemas. 135 * The description is the result of calling {@link ClassMeta#getName()}. 136 * The format is a comma-delimited list of any of the following values: 137 * 138 * <ul class='javatree'> 139 * <li class='jf'>{@link TypeCategory#BEAN BEAN} 140 * <li class='jf'>{@link TypeCategory#COLLECTION COLLECTION} 141 * <li class='jf'>{@link TypeCategory#ARRAY ARRAY} 142 * <li class='jf'>{@link TypeCategory#MAP MAP} 143 * <li class='jf'>{@link TypeCategory#STRING STRING} 144 * <li class='jf'>{@link TypeCategory#NUMBER NUMBER} 145 * <li class='jf'>{@link TypeCategory#BOOLEAN BOOLEAN} 146 * <li class='jf'>{@link TypeCategory#ANY ANY} 147 * <li class='jf'>{@link TypeCategory#OTHER OTHER} 148 * </ul> 149 * 150 * @param values 151 * The values to add to this setting. 152 * <br>The default is an empty string. 153 * <br>Cannot contain <jk>null</jk> values. 154 * @return This object. 155 */ 156 public Builder addDescriptionsTo(TypeCategory...values) { 157 reqnns("values", values); 158 addDescriptionsTo = addAll(addDescriptionsTo, values); 159 return this; 160 } 161 162 /** 163 * Add examples. 164 * 165 * <p> 166 * Identifies which categories of types that examples should be automatically added to generated schemas. 167 * <p> 168 * The examples come from calling {@link ClassMeta#getExample(MarshallingSession,JsonParserSession)} which in turn gets examples 169 * from the following: 170 * <ul class='javatree'> 171 * <li class='ja'>{@link Example} 172 * <li class='ja'>{@link Marshalled#example() Marshalled(example)} 173 * </ul> 174 * 175 * <p> 176 * The format is a comma-delimited list of any of the following values: 177 * 178 * <ul class='javatree'> 179 * <li class='jf'>{@link TypeCategory#BEAN BEAN} 180 * <li class='jf'>{@link TypeCategory#COLLECTION COLLECTION} 181 * <li class='jf'>{@link TypeCategory#ARRAY ARRAY} 182 * <li class='jf'>{@link TypeCategory#MAP MAP} 183 * <li class='jf'>{@link TypeCategory#STRING STRING} 184 * <li class='jf'>{@link TypeCategory#NUMBER NUMBER} 185 * <li class='jf'>{@link TypeCategory#BOOLEAN BOOLEAN} 186 * <li class='jf'>{@link TypeCategory#ANY ANY} 187 * <li class='jf'>{@link TypeCategory#OTHER OTHER} 188 * </ul> 189 * 190 * @param values 191 * The values to add to this setting. 192 * <br>The default is an empty string. 193 * <br>Cannot contain <jk>null</jk> values. 194 * @return This object. 195 */ 196 public Builder addExamplesTo(TypeCategory...values) { 197 reqnns("values", values); 198 addExamplesTo = addAll(addExamplesTo, values); 199 return this; 200 } 201 202 /** 203 * Allow nested descriptions. 204 * 205 * <p> 206 * Identifies whether nested descriptions are allowed in schema definitions. 207 * 208 * @return This object. 209 */ 210 public Builder allowNestedDescriptions() { 211 return allowNestedDescriptions(true); 212 } 213 214 /** 215 * Same as {@link #allowNestedDescriptions()} but allows you to explicitly specify the value. 216 * 217 * @param value The value for this setting. 218 * @return This object. 219 */ 220 public Builder allowNestedDescriptions(boolean value) { 221 allowNestedDescriptions = value; 222 return this; 223 } 224 225 /** 226 * Allow nested examples. 227 * 228 * <p> 229 * Identifies whether nested examples are allowed in schema definitions. 230 * 231 * @return This object. 232 */ 233 public Builder allowNestedExamples() { 234 return allowNestedExamples(true); 235 } 236 237 /** 238 * Same as {@link #allowNestedExamples()} but allows you to explicitly specify the value. 239 * 240 * @param value The value for this setting. 241 * @return This object. 242 */ 243 public Builder allowNestedExamples(boolean value) { 244 allowNestedExamples = value; 245 return this; 246 } 247 248 /** 249 * Schema definition mapper. 250 * 251 * <p> 252 * Interface to use for converting Bean classes to definition IDs and URIs. 253 * <p> 254 * Used primarily for defining common definition sections for beans in Swagger JSON. 255 * <p> 256 * This setting is ignored if {@link JsonSchemaGenerator.Builder#useBeanDefs()} is not enabled. 257 * 258 * @param value 259 * The new value for this setting. 260 * <br>The default is {@link BasicBeanDefMapper}. 261 * <br>Cannot be <jk>null</jk>. 262 * @return This object. 263 */ 264 public Builder beanDefMapper(Class<? extends MarshallingDefMapper> value) { 265 beanDefMapper = reqnn("value", value); 266 return this; 267 } 268 269 @Override /* Overridden from Context.Builder<?> */ 270 public JsonSchemaGenerator build() { 271 return cache(CACHE).build(JsonSchemaGenerator.class); 272 } 273 274 @Override /* Overridden from Context.Builder<?> */ 275 public Builder copy() { 276 return new Builder(this); 277 } 278 279 /** 280 * Gives access to the inner JSON parser builder if you want to modify the parser settings. 281 * 282 * @return The JSON serializer builder. 283 */ 284 public JsonParser.Builder<?> getJsonParserBuilder() { return jsonParserBuilder; } 285 286 /** 287 * Gives access to the inner JSON serializer builder if you want to modify the serializer settings. 288 * 289 * @return The JSON serializer builder. 290 */ 291 public JsonSerializer.Builder<?> getJsonSerializerBuilder() { return jsonSerializerBuilder; } 292 293 @Override /* Overridden from Context.Builder<?> */ 294 public HashKey hashKey() { 295 // @formatter:off 296 return HashKey.of( 297 super.hashKey(), 298 jsonSerializerBuilder.hashKey(), 299 jsonParserBuilder.hashKey(), 300 addDescriptionsTo, 301 addExamplesTo, 302 allowNestedDescriptions, 303 allowNestedExamples, 304 useBeanDefs, 305 beanDefMapper, 306 ignoreTypes 307 ); 308 // @formatter:on 309 } 310 311 /** 312 * Ignore types from schema definitions. 313 * 314 * <h4 class='section'>Description:</h4> 315 * <p> 316 * Defines class name patterns that should be ignored when generating schema definitions in the generated 317 * Swagger documentation. 318 * 319 * <h4 class='section'>Example:</h4> 320 * <p class='bjava'> 321 * <jc>// Don't generate schema for any prototype packages or the class named 'Swagger'.</jc> 322 * <ja>@JsonSchemaConfig</ja>( 323 * ignoreTypes=<js>"Swagger,*.proto.*"</js> 324 * ) 325 * <jk>public class</jk> MyResource {...} 326 * </p> 327 * 328 * @param values 329 * The values to add. 330 * <br>Cannot contain <jk>null</jk> values. 331 * @return This object. 332 */ 333 public Builder ignoreTypes(String...values) { 334 reqnns("values", values); 335 ignoreTypes = addAll(ignoreTypes, values); 336 return this; 337 } 338 339 /** 340 * Use bean definitions. 341 * 342 * <p> 343 * When enabled, schemas on beans will be serialized as the following: 344 * <p class='bjson'> 345 * { 346 * type: <js>'object'</js>, 347 * <js>'$ref'</js>: <js>'#/definitions/TypeId'</js> 348 * } 349 * </p> 350 * 351 * <p> 352 * The definitions can then be retrieved from the session using {@link JsonSchemaGeneratorSession#getBeanDefs()}. 353 * <p> 354 * Definitions can also be added programmatically using {@link JsonSchemaGeneratorSession#addBeanDef(String, JsonMap)}. 355 * 356 * @return This object. 357 */ 358 public Builder useBeanDefs() { 359 return useBeanDefs(true); 360 } 361 362 /** 363 * Same as {@link #useBeanDefs()} but allows you to explicitly specify the value. 364 * 365 * @param value The value for this setting. 366 * @return This object. 367 */ 368 public Builder useBeanDefs(boolean value) { 369 useBeanDefs = value; 370 return this; 371 } 372 373 374 } 375 376 /** Default serializer, all default settings.*/ 377 public static final JsonSchemaGenerator DEFAULT = new JsonSchemaGenerator(create()); 378 379 /** 380 * Creates a new builder for this object. 381 * 382 * @return A new builder. 383 */ 384 public static Builder create() { 385 return new Builder(); 386 } 387 388 protected final boolean allowNestedDescriptions; 389 protected final boolean allowNestedExamples; 390 protected final boolean useBeanDefs; 391 protected final Class<? extends MarshallingDefMapper> beanDefMapper; 392 protected final JsonParser jsonParser; 393 protected final JsonSerializer jsonSerializer; 394 protected final Set<TypeCategory> addDescriptionsTo; 395 protected final Set<TypeCategory> addExamplesTo; 396 protected final Set<String> ignoreTypes; 397 private final MarshallingDefMapper beanDefMapperBean; 398 private final Map<BeanPropertyMeta,JsonSchemaBeanPropertyMeta> jsonSchemaBeanPropertyMetas = new ConcurrentHashMap<>(); 399 private final Map<ClassMeta<?>,JsonSchemaClassMeta> jsonSchemaClassMetas = new ConcurrentHashMap<>(); 400 private final List<Pattern> ignoreTypePatterns; 401 402 /** 403 * Constructor. 404 * 405 * @param builder The builder for this object. Cannot be <jk>null</jk>. 406 */ 407 public JsonSchemaGenerator(Builder builder) { 408 super(builder.detectRecursions().ignoreRecursions()); 409 410 addDescriptionsTo = builder.addDescriptionsTo == null ? Collections.emptySet() : new TreeSet<>(builder.addDescriptionsTo); 411 addExamplesTo = builder.addExamplesTo == null ? Collections.emptySet() : new TreeSet<>(builder.addExamplesTo); 412 allowNestedDescriptions = builder.allowNestedDescriptions; 413 allowNestedExamples = builder.allowNestedExamples; 414 beanDefMapper = builder.beanDefMapper; 415 ignoreTypes = builder.ignoreTypes == null ? Collections.emptySet() : new TreeSet<>(builder.ignoreTypes); 416 useBeanDefs = builder.useBeanDefs; 417 418 Set<Pattern> ignoreTypePatterns2 = set(); 419 ignoreTypes.forEach(y -> split(y, x -> ignoreTypePatterns2.add(Pattern.compile(x.replace(".", "\\.").replace("*", ".*"))))); 420 this.ignoreTypePatterns = u(new ArrayList<>(ignoreTypePatterns2)); 421 422 try { 423 beanDefMapperBean = beanDefMapper.getDeclaredConstructor().newInstance(); 424 } catch (Exception e) { 425 throw toRex(e); 426 } 427 428 jsonSerializer = builder.jsonSerializerBuilder.build(); 429 jsonParser = builder.jsonParserBuilder.marshallingContext(getMarshallingContext()).build(); 430 } 431 432 @Override /* Overridden from Context */ 433 public Builder copy() { 434 return new Builder(this); 435 } 436 437 @Override /* Overridden from Context */ 438 public JsonSchemaGeneratorSession.Builder createSession() { 439 return JsonSchemaGeneratorSession.create(this); 440 } 441 442 /** 443 * Ignore types from schema definitions. 444 * 445 * @see Builder#ignoreTypes(String...) 446 * @return 447 * Custom schema information for particular class types. 448 * <br>Never <jk>null</jk>. 449 * <br>List is unmodifiable. 450 */ 451 public List<Pattern> getIgnoreTypes() { return ignoreTypePatterns; } 452 453 @Override 454 public JsonSchemaBeanPropertyMeta getJsonSchemaBeanPropertyMeta(BeanPropertyMeta bpm) { 455 return jsonSchemaBeanPropertyMetas.computeIfAbsent(bpm, k -> new JsonSchemaBeanPropertyMeta(k, this)); 456 } 457 458 @Override 459 public JsonSchemaClassMeta getJsonSchemaClassMeta(ClassMeta<?> cm) { 460 return jsonSchemaClassMetas.computeIfAbsent(cm, k -> new JsonSchemaClassMeta(k, this)); 461 } 462 463 @Override /* Overridden from Context */ 464 public JsonSchemaGeneratorSession getSession() { return createSession().build(); } 465 466 /** 467 * Returns <jk>true</jk> if the specified type is ignored. 468 * 469 * <p> 470 * The type is ignored if it's specified in the {@link Builder#ignoreTypes(String...)} setting. 471 * <br>Ignored types return <jk>null</jk> on the call to {@link JsonSchemaGeneratorSession#getSchema(ClassMeta)}. 472 * 473 * @param cm The type to check. Must not be <jk>null</jk>. 474 * @return <jk>true</jk> if the specified type is ignored. 475 */ 476 public boolean isIgnoredType(ClassMeta<?> cm) { 477 for (var p : ignoreTypePatterns) 478 if (p.matcher(cm.getNameSimple()).matches() || p.matcher(cm.getName()).matches()) 479 return true; 480 return false; 481 } 482 483 /** 484 * Add descriptions to types. 485 * 486 * @see Builder#addDescriptionsTo(TypeCategory...) 487 * @return 488 * Set of categories of types that descriptions should be automatically added to generated schemas. 489 */ 490 protected final Set<TypeCategory> getAddDescriptionsTo() { return addDescriptionsTo; } 491 492 /** 493 * Add examples. 494 * 495 * @see Builder#addExamplesTo(TypeCategory...) 496 * @return 497 * Set of categories of types that examples should be automatically added to generated schemas. 498 */ 499 protected final Set<TypeCategory> getAddExamplesTo() { return addExamplesTo; } 500 501 /** 502 * Bean schema definition mapper. 503 * 504 * @see Builder#beanDefMapper(Class) 505 * @return 506 * Interface to use for converting Bean classes to definition IDs and URIs. 507 */ 508 protected final MarshallingDefMapper getBeanDefMapper() { return beanDefMapperBean; } 509 510 /** 511 * Allow nested descriptions. 512 * 513 * @see Builder#allowNestedDescriptions() 514 * @return 515 * <jk>true</jk> if nested descriptions are allowed in schema definitions. 516 */ 517 protected final boolean isAllowNestedDescriptions() { return allowNestedDescriptions; } 518 519 /** 520 * Allow nested examples. 521 * 522 * @see Builder#allowNestedExamples() 523 * @return 524 * <jk>true</jk> if nested examples are allowed in schema definitions. 525 */ 526 protected final boolean isAllowNestedExamples() { return allowNestedExamples; } 527 528 /** 529 * Use bean definitions. 530 * 531 * @see Builder#useBeanDefs() 532 * @return 533 * <jk>true</jk> if schemas on beans will be serialized with <js>'$ref'</js> tags. 534 */ 535 protected final boolean isUseBeanDefs() { return useBeanDefs; } 536 537 @Override /* Overridden from MarshallingTraverseContext */ 538 protected FluentMap<String,Object> properties() { 539 return super.properties() 540 .a("addDescriptionsTo", addDescriptionsTo) 541 .a("addExamplesTo", addExamplesTo) 542 .a("allowNestedDescriptions", allowNestedDescriptions) 543 .a("allowNestedExamples", allowNestedExamples) 544 .a("beanDefMapper", beanDefMapper) 545 .a("ignoreTypes", ignoreTypes) 546 .a("useBeanDefs", useBeanDefs); 547 } 548 549 JsonParser getJsonParser() { return jsonParser; } 550 551 JsonSerializer getJsonSerializer() { return jsonSerializer; } 552}