OpenApi.Summary & OpenApi.Deprecated annotations (#3944)

Effect-TS · Nov 14, 2024 · 3aff4d3 · 3aff4d3
1 parent 7807f50
commit 3aff4d3
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 3 deletions.
diff --git a/.changeset/chilled-wolves-draw.md b/.changeset/chilled-wolves-draw.md
@@ -0,0 +1,5 @@
+---
+"@effect/platform": patch
+---
+
+`OpenApi.Summary` & `OpenApi.Deprecated` annotations have been added
diff --git a/packages/platform-node/test/HttpApi.test.ts b/packages/platform-node/test/HttpApi.test.ts
@@ -280,6 +280,8 @@ class UsersApi extends HttpApiGroup.make("users")
       }))
       .addSuccess(Schema.Array(User))
       .addError(NoStatusError)
+      .annotate(OpenApi.Deprecated, true)
+      .annotate(OpenApi.Summary, "test summary")
       .annotateContext(OpenApi.annotations({ identifier: "listUsers" }))
   )
   .add(
@@ -302,7 +304,7 @@ class Api extends HttpApi.empty
   .addHttpApi(AnotherApi)
   .add(UsersApi.prefix("/users"))
   .addError(GlobalError, { status: 413 })
-  .annotateContext(OpenApi.annotations({ title: "API" }))
+  .annotateContext(OpenApi.annotations({ title: "API", summary: "test api summary" }))
 {}
 
 // impl

diff --git a/packages/platform-node/test/fixtures/openapi.json b/packages/platform-node/test/fixtures/openapi.json
@@ -2,7 +2,8 @@
   "openapi": "3.0.3",
   "info": {
     "title": "API",
-    "version": "0.0.1"
+    "version": "0.0.1",
+    "summary": "test api summary"
   },
   "paths": {
     "/groups/{id}": {
@@ -247,7 +248,11 @@
         }
       },
       "get": {
-        "tags": ["Users API"],
+        "tags": [
+          "Users API"
+        ],
+        "deprecated": true,
+        "summary": "test summary",
         "operationId": "listUsers",
         "parameters": [
           {

diff --git a/packages/platform/src/OpenApi.ts b/packages/platform/src/OpenApi.ts
@@ -67,6 +67,18 @@ export class Servers
  */
 export class Format extends Context.Tag("@effect/platform/OpenApi/Format")<Format, string>() {}
 
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export class Summary extends Context.Tag("@effect/platform/OpenApi/Summary")<Summary, string>() {}
+
+/**
+ * @since 1.0.0
+ * @category annotations
+ */
+export class Deprecated extends Context.Tag("@effect/platform/OpenApi/Deprecated")<Deprecated, boolean>() {}
+
 /**
  * @since 1.0.0
  * @category annotations
@@ -98,6 +110,7 @@ export const annotations: (
   options: {
     readonly identifier?: string | undefined
     readonly title?: string | undefined
+    readonly summary?: string | undefined
     readonly version?: string | undefined
     readonly description?: string | undefined
     readonly license?: OpenAPISpecLicense | undefined
@@ -112,6 +125,7 @@ export const annotations: (
   version: Version,
   description: Description,
   license: License,
+  summary: Summary,
   externalDocs: ExternalDocs,
   servers: Servers,
   format: Format,
@@ -166,6 +180,9 @@ export const fromApi = <A extends HttpApi.HttpApi.Any>(self: A): OpenAPISpec =>
   Option.map(Context.getOption(api.annotations, License), (license) => {
     spec.info.license = license
   })
+  Option.map(Context.getOption(api.annotations, Summary), (summary) => {
+    spec.info.summary = summary as any
+  })
   Option.map(Context.getOption(api.annotations, Servers), (servers) => {
     spec.servers = servers as any
   })
@@ -214,6 +231,12 @@ export const fromApi = <A extends HttpApi.HttpApi.Any>(self: A): OpenAPISpec =>
       Option.map(Context.getOption(endpoint.annotations, Description), (description) => {
         op.description = description
       })
+      Option.map(Context.getOption(endpoint.annotations, Summary), (summary) => {
+        op.summary = summary
+      })
+      Option.map(Context.getOption(endpoint.annotations, Deprecated), (deprecated) => {
+        op.deprecated = deprecated
+      })
       Option.map(Context.getOption(endpoint.annotations, ExternalDocs), (externalDocs) => {
         op.externalDocs = externalDocs
       })
@@ -413,6 +436,7 @@ export interface OpenAPISpecInfo {
   readonly version: string
   readonly description?: string
   readonly license?: OpenAPISpecLicense
+  readonly summary?: string
 }
 
 /**