Better inference of infallible schemas when generating OpenAPI docs

softwaremill · Jan 16, 2025 · d8cfc92 · d8cfc92
1 parent cc36eb2
commit d8cfc92
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 6 deletions.
diff --git a/...napi-docs/src/main/scala/sttp/tapir/docs/openapi/EndpointInputToDecodeFailureOutput.scala b/...napi-docs/src/main/scala/sttp/tapir/docs/openapi/EndpointInputToDecodeFailureOutput.scala
@@ -29,7 +29,15 @@ private[openapi] object EndpointInputToDecodeFailureOutput {
     codec.format.mediaType != MediaType.TextPlain ||
       codec.schema.hasValidation ||
       codec.schema.format.nonEmpty ||
-      codec.schema.schemaType != SchemaType.SString()
+      decodingMayFail(codec.schema.schemaType)
+
+  private def decodingMayFail(st: SchemaType[_]): Boolean = st match {
+    case SchemaType.SString()        => false
+    case SchemaType.SBinary()        => false
+    case SchemaType.SOption(element) => decodingMayFail(element.schemaType)
+    case SchemaType.SArray(element)  => decodingMayFail(element.schemaType)
+    case _                           => true
+  }
 
   private def badRequestDescription(fallibleBasicInputs: Vector[EndpointInput.Basic[_]]) =
     fallibleBasicInputs.map(failureSourceMessage).distinct.mkString(", ")

diff --git a/.../openapi-docs/src/test/resources/example/expected_examples_of_list_and_not_list_types.yml b/.../openapi-docs/src/test/resources/example/expected_examples_of_list_and_not_list_types.yml
@@ -36,8 +36,8 @@ paths:
         '200':
           description: ''
         '400':
-          description: 'Invalid value for: query parameter friends, Invalid value
-                        for: query parameter current-person, Invalid value for: body'
+          description: 'Invalid value for: query parameter current-person, Invalid
+                        value for: body'
           content:
             text/plain:
               schema:

diff --git a/docs/openapi-docs/src/test/resources/expected_array_no_format.yml b/docs/openapi-docs/src/test/resources/expected_array_no_format.yml
@@ -26,8 +26,7 @@ paths:
         '200':
           description: ''
         '400':
-          description: 'Invalid value for: query parameter foo, Invalid value for:
-                        query parameter bar'
+          description: 'Invalid value for: query parameter bar'
           content:
             text/plain:
               schema:

diff --git a/docs/openapi-docs/src/test/resources/expected_optional_header.yml b/docs/openapi-docs/src/test/resources/expected_optional_header.yml
@@ -0,0 +1,17 @@
+openapi: 3.1.0
+info:
+  title: Entities
+  version: '1.0'
+paths:
+  /:
+    post:
+      operationId: postRoot
+      parameters:
+      - name: X-test
+        in: header
+        required: false
+        schema:
+          type: string
+      responses:
+        '200':
+          description: ''
diff --git a/docs/openapi-docs/src/test/scalajvm/sttp/tapir/docs/openapi/VerifyYamlTest.scala b/docs/openapi-docs/src/test/scalajvm/sttp/tapir/docs/openapi/VerifyYamlTest.scala
@@ -874,7 +874,16 @@ class VerifyYamlTest extends AnyFunSuite with Matchers {
     val e = endpoint.post.in("double").in(stringBody)
 
     val expectedYaml = load("expected_string_body_response.yml")
-    val codec = Codec.listHead(Codec.json[String](DecodeResult.Value(_))(identity))
+    val actualYaml = OpenAPIDocsInterpreter().toOpenAPI(e, Info("Entities", "1.0")).toYaml
+
+    val actualYamlNoIndent = noIndentation(actualYaml)
+    actualYamlNoIndent shouldBe expectedYaml
+  }
+
+  test("should not include '400 invalid value for: header' response if an optional string header is used") {
+    val e = endpoint.post.in(header[Option[String]]("X-test"))
+
+    val expectedYaml = load("expected_optional_header.yml")
     val actualYaml = OpenAPIDocsInterpreter().toOpenAPI(e, Info("Entities", "1.0")).toYaml
 
     val actualYamlNoIndent = noIndentation(actualYaml)