From 853c4a4968daee390c4fdac97f150bfc5d03abf5 Mon Sep 17 00:00:00 2001
From: Phillip Kruger <phillip.kruger@gmail.com>
Date: Wed, 20 Mar 2024 11:03:34 +1100
Subject: [PATCH] Add a section about openapi filters in the doc

Signed-off-by: Phillip Kruger <phillip.kruger@gmail.com>
---
 docs/src/main/asciidoc/openapi-swaggerui.adoc | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/src/main/asciidoc/openapi-swaggerui.adoc b/docs/src/main/asciidoc/openapi-swaggerui.adoc
index a97150ad81572..9833a044b8f7f 100644
--- a/docs/src/main/asciidoc/openapi-swaggerui.adoc
+++ b/docs/src/main/asciidoc/openapi-swaggerui.adoc
@@ -322,6 +322,46 @@ quarkus.smallrye-openapi.info-license-url=https://www.apache.org/licenses/LICENS
 
 This will give you similar information as the `@OpenAPIDefinition` example above.
 
+== Enhancing the OpenAPI Schema with Filters
+
+You can change the Generated OpenAPI Schema using one or more filter. Filters can run during build time, or at runtime.
+
+[source,java]
+----
+/**
+ * Filter to add custom elements
+ */
+@OpenApiFilter(OpenApiFilter.RunStage.BUILD) //<1>
+public class MyBuildTimeFilter implements OASFilter { //<2>
+
+    private IndexView view;
+
+    public MyBuildTimeFilter(IndexView view) { //<3>
+        this.view = view;
+    }
+
+    @Override
+    public void filterOpenAPI(OpenAPI openAPI) { //<4>
+        Collection<ClassInfo> knownClasses = this.view.getKnownClasses();
+        Info info = OASFactory.createInfo();
+        info.setDescription("Created from Annotated Buildtime filter with " + knownClasses.size() + " known indexed classes");
+        openAPI.setInfo(info);
+    }
+
+}
+----
+<1> Annotate method with `@OpenApiFilter` and the run stage (BUILD,RUN,BOTH)
+<2> Implement OASFilter and override any of the methods
+<3> For Build stage filters, the index can be passed in (optional)
+<4> Get a hold of the generated `OpenAPI` Schema, and enhance as required
+
+Remember that setting fields on the schema will override what has been generated, you might want to get and add to (so modify). Also know that the generated values might be null, so you will have to check for that.
+
+=== Runtime filters
+
+Runtime filters by default runs on startup (when the final OpenAPI document gets created). You can change runtime filters to run on every request, making the openapi document dynamic.
+To do this you need to set this propery: `quarkus.smallrye-openapi.always-run-filter=true`.
+
 == Loading OpenAPI Schema From Static Files
 
 Instead of dynamically creating OpenAPI schemas from annotation scanning, Quarkus also supports serving static OpenAPI documents.