chore: add missing doc

utybo · Oct 30, 2024 · 26c90c0 · 26c90c0
1 parent 6943f6e
commit 26c90c0
Show file tree

Hide file tree

Showing 3 changed files with 50 additions and 7 deletions.
diff --git a/tegral-openapi/tegral-openapi-dsl/api/tegral-openapi-dsl.api b/tegral-openapi/tegral-openapi-dsl/api/tegral-openapi-dsl.api
@@ -199,16 +199,18 @@ public final class guru/zoroark/tegral/openapi/dsl/OperationBuilder : guru/zoroa
 	public fun response (ILkotlin/jvm/functions/Function1;)V
 	public fun security (Ljava/lang/String;)V
 	public fun security (Ljava/lang/String;[Ljava/lang/String;)V
+	public fun security (Lkotlin/jvm/functions/Function1;)V
 	public fun setDeprecated (Ljava/lang/Boolean;)V
 	public fun setDescription (Ljava/lang/String;)V
 	public fun setExternalDocsDescription (Ljava/lang/String;)V
 	public fun setExternalDocsUrl (Ljava/lang/String;)V
 	public fun setOperationId (Ljava/lang/String;)V
 	public fun setRequestBody (Lguru/zoroark/tegral/openapi/dsl/RequestBodyBuilder;)V
+	public fun setSecurityRequirements (Ljava/util/List;)V
 	public fun setSummary (Ljava/lang/String;)V
 }
 
-public abstract interface class guru/zoroark/tegral/openapi/dsl/OperationDsl {
+public abstract interface class guru/zoroark/tegral/openapi/dsl/OperationDsl : guru/zoroark/tegral/openapi/dsl/SecurityDsl {
 	public abstract fun body (Lkotlin/jvm/functions/Function1;)V
 	public abstract fun cookieParameter (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public abstract fun getDeprecated ()Ljava/lang/Boolean;
@@ -219,15 +221,12 @@ public abstract interface class guru/zoroark/tegral/openapi/dsl/OperationDsl {
 	public abstract fun getParameters ()Ljava/util/List;
 	public abstract fun getRequestBody ()Lguru/zoroark/tegral/openapi/dsl/RequestBodyBuilder;
 	public abstract fun getResponses ()Ljava/util/Map;
-	public abstract fun getSecurityRequirements ()Ljava/util/List;
 	public abstract fun getSummary ()Ljava/lang/String;
 	public abstract fun getTags ()Ljava/util/List;
 	public abstract fun headerParameter (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public abstract fun pathParameter (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public abstract fun queryParameter (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public abstract fun response (ILkotlin/jvm/functions/Function1;)V
-	public abstract fun security (Ljava/lang/String;)V
-	public abstract fun security (Ljava/lang/String;[Ljava/lang/String;)V
 	public abstract fun setDeprecated (Ljava/lang/Boolean;)V
 	public abstract fun setDescription (Ljava/lang/String;)V
 	public abstract fun setExternalDocsDescription (Ljava/lang/String;)V
@@ -332,6 +331,7 @@ public final class guru/zoroark/tegral/openapi/dsl/PathBuilder : guru/zoroark/te
 	public fun response (ILkotlin/jvm/functions/Function1;)V
 	public fun security (Ljava/lang/String;)V
 	public fun security (Ljava/lang/String;[Ljava/lang/String;)V
+	public fun security (Lkotlin/jvm/functions/Function1;)V
 	public fun setDelete (Lguru/zoroark/tegral/openapi/dsl/OperationBuilder;)V
 	public fun setDeprecated (Ljava/lang/Boolean;)V
 	public fun setDescription (Ljava/lang/String;)V
@@ -479,6 +479,7 @@ public final class guru/zoroark/tegral/openapi/dsl/RootBuilder : guru/zoroark/te
 	public fun getLicenseIdentifier ()Ljava/lang/String;
 	public fun getLicenseName ()Ljava/lang/String;
 	public fun getLicenseUrl ()Ljava/lang/String;
+	public fun getSecurityRequirements ()Ljava/util/List;
 	public fun getSummary ()Ljava/lang/String;
 	public fun getTermsOfService ()Ljava/lang/String;
 	public fun getTitle ()Ljava/lang/String;
@@ -489,6 +490,9 @@ public final class guru/zoroark/tegral/openapi/dsl/RootBuilder : guru/zoroark/te
 	public fun patch (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun post (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun put (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public fun security (Ljava/lang/String;)V
+	public fun security (Ljava/lang/String;[Ljava/lang/String;)V
+	public fun security (Lkotlin/jvm/functions/Function1;)V
 	public fun securityScheme (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun server (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun setContactEmail (Ljava/lang/String;)V
@@ -500,14 +504,15 @@ public final class guru/zoroark/tegral/openapi/dsl/RootBuilder : guru/zoroark/te
 	public fun setLicenseIdentifier (Ljava/lang/String;)V
 	public fun setLicenseName (Ljava/lang/String;)V
 	public fun setLicenseUrl (Ljava/lang/String;)V
+	public fun setSecurityRequirements (Ljava/util/List;)V
 	public fun setSummary (Ljava/lang/String;)V
 	public fun setTermsOfService (Ljava/lang/String;)V
 	public fun setTitle (Ljava/lang/String;)V
 	public fun setVersion (Ljava/lang/String;)V
 	public fun tag (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 }
 
-public abstract interface class guru/zoroark/tegral/openapi/dsl/RootDsl : guru/zoroark/tegral/openapi/dsl/InfoDsl, guru/zoroark/tegral/openapi/dsl/PathsDsl, guru/zoroark/tegral/openapi/dsl/TagsDsl {
+public abstract interface class guru/zoroark/tegral/openapi/dsl/RootDsl : guru/zoroark/tegral/openapi/dsl/InfoDsl, guru/zoroark/tegral/openapi/dsl/PathsDsl, guru/zoroark/tegral/openapi/dsl/SecurityDsl, guru/zoroark/tegral/openapi/dsl/TagsDsl {
 	public abstract fun getExternalDocsDescription ()Ljava/lang/String;
 	public abstract fun getExternalDocsUrl ()Ljava/lang/String;
 	public abstract fun securityScheme (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
@@ -516,6 +521,21 @@ public abstract interface class guru/zoroark/tegral/openapi/dsl/RootDsl : guru/z
 	public abstract fun setExternalDocsUrl (Ljava/lang/String;)V
 }
 
+public abstract interface class guru/zoroark/tegral/openapi/dsl/SecurityDsl {
+	public abstract fun getSecurityRequirements ()Ljava/util/List;
+	public abstract fun security (Ljava/lang/String;)V
+	public abstract fun security (Ljava/lang/String;[Ljava/lang/String;)V
+	public abstract fun security (Lkotlin/jvm/functions/Function1;)V
+}
+
+public final class guru/zoroark/tegral/openapi/dsl/SecurityRequirementsBuilder : guru/zoroark/tegral/core/Buildable {
+	public fun <init> ()V
+	public fun build ()Lio/swagger/v3/oas/models/security/SecurityRequirement;
+	public synthetic fun build ()Ljava/lang/Object;
+	public final fun requirement (Ljava/lang/String;)V
+	public final fun requirement (Ljava/lang/String;[Ljava/lang/String;)V
+}
+
 public final class guru/zoroark/tegral/openapi/dsl/SecuritySchemeBuilder : guru/zoroark/tegral/core/Buildable, guru/zoroark/tegral/openapi/dsl/SecuritySchemeDsl {
 	public fun <init> ()V
 	public fun build ()Lio/swagger/v3/oas/models/security/SecurityScheme;

diff --git a/...openapi/tegral-openapi-dsl/src/main/kotlin/guru/zoroark/tegral/openapi/dsl/SecurityDsl.kt b/...openapi/tegral-openapi-dsl/src/main/kotlin/guru/zoroark/tegral/openapi/dsl/SecurityDsl.kt
@@ -14,9 +14,15 @@
 
 package guru.zoroark.tegral.openapi.dsl
 
+import guru.zoroark.tegral.core.Buildable
 import guru.zoroark.tegral.core.TegralDsl
 import io.swagger.v3.oas.models.security.SecurityRequirement
 
+/**
+ * DSL for the [security item object](https://spec.openapis.org/oas/v3.1.0#security-requirement-object).
+ *
+ * Can be defined at root level (see [RootDsl]) and operation level (see [OperationDsl]).
+ */
 @TegralDsl
 interface SecurityDsl {
     /**
@@ -41,20 +47,33 @@ interface SecurityDsl {
     @TegralDsl
     fun security(key: String, vararg scopes: String)
 
+    /**
+     * Adds a security requirement object using the provided builder.
+     * Allows to define multiple requirements (which behave like an "AND", and all of them need to be fulfilled).
+     */
     @TegralDsl
     fun security(builder: SecurityRequirementsBuilder.() -> Unit)
 }
 
-class SecurityRequirementsBuilder {
+/**
+ * Builder for [SecurityRequirement]
+ */
+class SecurityRequirementsBuilder : Buildable<SecurityRequirement> {
     private val securityRequirement = SecurityRequirement()
 
+    /**
+     * Adds a security requirement object with the given key.
+     */
     fun requirement(key: String) {
         securityRequirement.addList(key)
     }
 
+    /**
+     * Adds a security requirement object with the given key and scopes.
+     */
     fun requirement(key: String, vararg scopes: String) {
         securityRequirement.addList(key, scopes.asList())
     }
 
-    fun build(): SecurityRequirement = securityRequirement
+    override fun build(): SecurityRequirement = securityRequirement
 }
diff --git a/tegral-openapi/tegral-openapi-ktor/api/tegral-openapi-ktor.api b/tegral-openapi/tegral-openapi-ktor/api/tegral-openapi-ktor.api
@@ -38,6 +38,7 @@ public final class guru/zoroark/tegral/openapi/ktor/TegralOpenApiKtor$Configurat
 	public fun getLicenseIdentifier ()Ljava/lang/String;
 	public fun getLicenseName ()Ljava/lang/String;
 	public fun getLicenseUrl ()Ljava/lang/String;
+	public fun getSecurityRequirements ()Ljava/util/List;
 	public fun getSummary ()Ljava/lang/String;
 	public fun getTermsOfService ()Ljava/lang/String;
 	public fun getTitle ()Ljava/lang/String;
@@ -48,6 +49,9 @@ public final class guru/zoroark/tegral/openapi/ktor/TegralOpenApiKtor$Configurat
 	public fun patch (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun post (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun put (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
+	public fun security (Ljava/lang/String;)V
+	public fun security (Ljava/lang/String;[Ljava/lang/String;)V
+	public fun security (Lkotlin/jvm/functions/Function1;)V
 	public fun securityScheme (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun server (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
 	public fun setContactEmail (Ljava/lang/String;)V