Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: display endpoint documentation in swagger ui #3221

Merged
merged 9 commits into from
Mar 5, 2025
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,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",
Expand All @@ -278,7 +300,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",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -659,7 +659,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).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))
Expand Down Expand Up @@ -701,7 +702,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,
Expand Down
Loading