From ebcc80301d793fb33c911e2da501e5dc9a210750 Mon Sep 17 00:00:00 2001 From: Michael Edgar Date: Fri, 15 Mar 2024 14:23:09 -0400 Subject: [PATCH] WIP: add JavaDocs for new builder API Signed-off-by: Michael Edgar --- .../smallrye/openapi/api/SmallRyeOpenAPI.java | 93 ++++++++++++++++++- 1 file changed, 92 insertions(+), 1 deletion(-) diff --git a/core/src/main/java/io/smallrye/openapi/api/SmallRyeOpenAPI.java b/core/src/main/java/io/smallrye/openapi/api/SmallRyeOpenAPI.java index 2c4599434..1c2b89a93 100644 --- a/core/src/main/java/io/smallrye/openapi/api/SmallRyeOpenAPI.java +++ b/core/src/main/java/io/smallrye/openapi/api/SmallRyeOpenAPI.java @@ -104,46 +104,137 @@ public static class Builder { private Builder() { } + /** + * Set the MicroProfile Config to be used when building the OpenAPI + * model. When not set, the builder will obtain a Config instance using + * {@link ConfigProvider#getConfig()} with the + * {@linkplain #withApplicationClassLoader(ClassLoader) application + * class loader}. + * + * @param config + * Config instance, nulls not allowed + * @return this builder + */ public Builder withConfig(Config config) { this.config = Objects.requireNonNull(config); return this; } + /** + * Set the application ClassLoader to be used when building the OpenAPI + * model. + * + * @param classLoader + * ClassLoader instance, nulls not allowed + * @return this builder + */ public Builder withApplicationClassLoader(ClassLoader classLoader) { this.applicationClassLoader = Objects.requireNonNull(classLoader); return this; } + /** + * Set an initial model used when building the OpenAPI model. The + * elements in this model will be overridden by any conflicting elements + * in models generated by the builder. + * + * @param initialModel + * initial OpenAPI model + * @return this builder + */ public Builder withInitialModel(OpenAPI initialModel) { this.initialModel = initialModel; return this; } + /** + * Enable (true) or disable (false) the lookup and use of an + * OASModelReader. Default is true. + * + * @param enableModelReader + * true if the model reader should be loaded and called, + * otherwise false. + * @return this builder + */ public Builder enableModelReader(boolean enableModelReader) { this.enableModelReader = enableModelReader; return this; } + /** + * Enable (true) or disable (false) the lookup and use of the standard + * static OpenAPI files (e.g. {@code META-INF/openapi.(json|yaml|yml)}. + * Default is true. + * + * @param enableStandardStaticFiles + * true if the standard static files should be loaded and + * included, otherwise false. + * @return this builder + */ public Builder enableStandardStaticFiles(boolean enableStandardStaticFiles) { this.enableStandardStaticFiles = enableStandardStaticFiles; return this; } + /** + * Enable (true) or disable (false) the lookup and use of the standard + * OASFilter. Default is true. + * + * @param enableStandardFilter + * true if the filter should be loaded and called, otherwise + * false. + * @return this builder + */ public Builder enableStandardFilter(boolean enableStandardFilter) { this.enableStandardFilter = enableStandardFilter; return this; } + /** + * Enable (true) or disable (false) setting default values for the + * OpenAPI properties listed below. Default is true. + * + * + * + * @param defaultRequiredProperties + * true if default values should be set when necessary, + * otherwise false. + * @return this builder + */ public Builder defaultRequiredProperties(boolean defaultRequiredProperties) { this.defaultRequiredProperties = defaultRequiredProperties; return this; } + /** + * Provide a resource locator function that when given a String path for + * a static file will return a URL that may be used to load the + * resource. This function is intended to support environments where the + * resource is not on the class path and an alternate loading approach + * is necessary, for example using a ServletContext. + * + * @param resourceLocator + * @return this builder + */ public Builder withResourceLocator(Function resourceLocator) { this.resourceLocator = resourceLocator; return this; } + /** + * Provide a custom static file that is not one of those in the standard locations + * or with a standard name. The user of this builder is responsible for closing the stream + * after {@linkplain #build()} has been invoked. + * + * @param customStaticFile + * @return + */ public Builder withCustomStaticFile(InputStream customStaticFile) { this.customStaticFile = customStaticFile; return this; @@ -225,7 +316,7 @@ public SmallRyeOpenAPI build() { : Thread.currentThread().getContextClassLoader(); OpenApiConfig buildConfig = OpenApiConfig.fromConfig(Optional.ofNullable(this.config) - .orElseGet(ConfigProvider::getConfig)); + .orElseGet(() -> ConfigProvider.getConfig(appClassLoader))); IOContext io = IOContext.forJson(JsonIO.newInstance(buildConfig)); OpenAPIDefinitionIO modelIO = new OpenAPIDefinitionIO<>(io); FilteredIndexView filteredIndex = new FilteredIndexView(index, buildConfig);