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}