From 084e2fa652246c4740fa9236d50b4ed5e64d56ef Mon Sep 17 00:00:00 2001 From: Eddy Oyieko <67474838+mobley-trent@users.noreply.github.com> Date: Tue, 26 Nov 2024 14:50:02 +0000 Subject: [PATCH 1/2] fix: display endpoint documentation in swagger ui --- .../endpoint/openapi/OpenAPIGenSpec.scala | 24 ++++++++++++++++++- .../http/endpoint/openapi/OpenAPIGen.scala | 4 ++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala index 73ceede3a0..d0b9997ae7 100644 --- a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala +++ b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala @@ -250,6 +250,28 @@ object OpenAPIGenSpec extends ZIOSpecDefault { |}""".stripMargin assertTrue(json == toJsonAst(expectedJson)) }, + test("endpoint documentation") { + val genericEndpoint = Endpoint(GET / "users") ?? Doc.p("Get all users") + val generated = OpenAPIGen.fromEndpoints("Generic Endpoint", "1.0", genericEndpoint) + val json = toJsonAst(generated) + val expectedJson = """{ + | "openapi" : "3.1.0", + | "info" : { + | "title" : "Generic Endpoint", + | "version" : "1.0" + | }, + | "paths" : { + | "/users" : { + | "description" : "Get all users\n\n", + | "get" : { + | "description" : "Get all users\n\n" + | } + | } + | }, + | "components" : {} + |}""".stripMargin + assertTrue(json == toJsonAst(expectedJson)) + }, test("simple endpoint to OpenAPI") { val generated = OpenAPIGen.fromEndpoints( "Simple Endpoint", @@ -271,7 +293,7 @@ object OpenAPIGenSpec extends ZIOSpecDefault { | "simple", | "endpoint" | ], - | "description" : "get path\n\n", + | "description" : "some extra doc\n\nget path\n\n- simple\n- endpoint\n", | "parameters" : [ | { | "name" : "id", diff --git a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala index 64ba057807..efbbd040c1 100644 --- a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala +++ b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala @@ -538,7 +538,7 @@ object OpenAPIGen { val path = buildPath(endpoint.input) val method0 = method(inAtoms.method) // Endpoint has only one doc. But open api has a summery and a description - val pathItem = OpenAPI.PathItem.empty.copy(description = Some(endpoint.documentation).filter(!_.isEmpty)) + val pathItem = OpenAPI.PathItem.empty.copy(description = Some(endpoint.documentation + endpoint.input.doc.getOrElse(Doc.empty)).filter(!_.isEmpty)) val pathItemWithOp = method0 match { case Method.OPTIONS => pathItem.addOptions(operation(endpoint)) case Method.GET => pathItem.addGet(operation(endpoint)) @@ -580,7 +580,7 @@ object OpenAPIGen { } def operation(endpoint: Endpoint[_, _, _, _, _]): OpenAPI.Operation = { - val maybeDoc = Some(pathDoc).filter(!_.isEmpty) + val maybeDoc = Some(endpoint.documentation + pathDoc).filter(!_.isEmpty) OpenAPI.Operation( tags = endpoint.tags, summary = None, From 73c34e6a83065984cf0ac7d5807846a62b4442a9 Mon Sep 17 00:00:00 2001 From: Eddy Oyieko <67474838+mobley-trent@users.noreply.github.com> Date: Tue, 26 Nov 2024 14:58:39 +0000 Subject: [PATCH 2/2] sbt fmt --- .../endpoint/openapi/OpenAPIGenSpec.scala | 30 +++++++++---------- .../http/endpoint/openapi/OpenAPIGen.scala | 3 +- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala index d0b9997ae7..4851af366d 100644 --- a/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala +++ b/zio-http/jvm/src/test/scala/zio/http/endpoint/openapi/OpenAPIGenSpec.scala @@ -255,21 +255,21 @@ object OpenAPIGenSpec extends ZIOSpecDefault { val generated = OpenAPIGen.fromEndpoints("Generic Endpoint", "1.0", genericEndpoint) val json = toJsonAst(generated) val expectedJson = """{ - | "openapi" : "3.1.0", - | "info" : { - | "title" : "Generic Endpoint", - | "version" : "1.0" - | }, - | "paths" : { - | "/users" : { - | "description" : "Get all users\n\n", - | "get" : { - | "description" : "Get all users\n\n" - | } - | } - | }, - | "components" : {} - |}""".stripMargin + | "openapi" : "3.1.0", + | "info" : { + | "title" : "Generic Endpoint", + | "version" : "1.0" + | }, + | "paths" : { + | "/users" : { + | "description" : "Get all users\n\n", + | "get" : { + | "description" : "Get all users\n\n" + | } + | } + | }, + | "components" : {} + |}""".stripMargin assertTrue(json == toJsonAst(expectedJson)) }, test("simple endpoint to OpenAPI") { diff --git a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala index efbbd040c1..19727820ae 100644 --- a/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala +++ b/zio-http/shared/src/main/scala/zio/http/endpoint/openapi/OpenAPIGen.scala @@ -538,7 +538,8 @@ object OpenAPIGen { val path = buildPath(endpoint.input) val method0 = method(inAtoms.method) // Endpoint has only one doc. But open api has a summery and a description - val pathItem = OpenAPI.PathItem.empty.copy(description = Some(endpoint.documentation + endpoint.input.doc.getOrElse(Doc.empty)).filter(!_.isEmpty)) + val pathItem = OpenAPI.PathItem.empty + .copy(description = Some(endpoint.documentation + endpoint.input.doc.getOrElse(Doc.empty)).filter(!_.isEmpty)) val pathItemWithOp = method0 match { case Method.OPTIONS => pathItem.addOptions(operation(endpoint)) case Method.GET => pathItem.addGet(operation(endpoint))