@nxgt/typespec 0.13.2 → 0.14.0

package/docs/guide/emitter.md

@@ -2,7 +2,9 @@
 
 `@nxgt/typespec` is a TypeSpec emitter as well as a library: it compiles a
 spec to OpenAPI with `@typespec/openapi3`, and writes each `@queryMethod` as a
-real `QUERY` when the document is OpenAPI 3.2.
+real `QUERY` when the document is OpenAPI 3.2. It also emits a shared
+response or header once under `components`, and `servers` on one path
+([below](#shared-responses-shared-headers-and-path-servers)).
 
 ## The smallest setup
 
@@ -98,6 +100,150 @@ where `@typespec/openapi3` wrote `tsp-output/@typespec/openapi3`. Set
 `@typespec/openapi3` is loaded only when emitting, so a spec that only
 imports the library, `tsp compile --no-emit`, does not need it installed.
 
+## Shared responses, shared headers and path servers
+
+`@typespec/openapi3` writes every response and header in full at each
+operation, and `@server` only reaches the document's `servers`. Three
+decorators ask the emitter for the rest, with no post-processing of the JSON.
+They need this emitter: with `@typespec/openapi3` in `emit` each is the error
+`shared-needs-nxgt-emitter`, since it would write the copies or drop the
+servers without a word.
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Example" })
+@server("https://api.example.com", "Main")
+namespace Example;
+
+model NoStore {
+  @sharedHeader("NoStore")
+  @header("cache-control")
+  cacheControl: "no-store";
+}
+
+@sharedResponse
+@error
+model Unauthorized {
+  ...NoStore;
+  @statusCode code: 401;
+  message: string;
+}
+
+@route("/items") @get op listItems(): { @body items: string[] } | Unauthorized;
+
+@route("/users")
+@pathServer("https://users.example.com", "Users")
+@get op listUsers(): { @body users: string[] } | Unauthorized;
+```
+
+```yaml
+# openapi.yaml (extract)
+paths:
+  /items:
+    get:
+      responses:
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /users:
+    servers:
+      - url: https://users.example.com
+        description: Users
+    get:
+      responses:
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+components:
+  headers:
+    NoStore:
+      required: true
+      schema: { type: string, enum: [no-store] }
+  responses:
+    Unauthorized:
+      description: Access is unauthorized.
+      headers:
+        cache-control:
+          $ref: '#/components/headers/NoStore'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Unauthorized'
+servers:
+  - url: https://api.example.com
+    description: Main
+```
+
+| Decorator | On | Result |
+| --- | --- | --- |
+| `@sharedResponse(name?)` | a response model | each reply of that model, whatever the operation, is one entry of `components.responses` (named after the model unless `name` is given) and a `$ref` at each use |
+| `@sharedHeader(name?)` | a model property that is a `@header` | the header is one entry of `components.headers` (named after the property unless `name` is given) and a `$ref` at each response that carries it |
+| `@pathServer(url, description?, parameters?)` | an operation | `servers` on the operation's path item; the other paths keep the document's. Repeated on the operations of one path, the servers add up |
+
+What to know:
+
+- **A response header only.** `components.headers` holds response headers.
+  `@sharedHeader` on a request `@header` or on a body property is the error
+  `shared-header-misplaced`; the mark never stays in the document.
+- **A shared response is the whole reply**: description, headers and content.
+  A model with several statuses (`@statusCode code: 400 | 404`) is one
+  component per status, `Name400` and `Name404`, since their descriptions
+  differ.
+  Two shared responses, or two shared headers, of one name that differ are the
+  error `shared-component-conflict`: the first is the component, the other
+  stays inline. A name is letters,
+  digits, `.`, `_` and `-` (`invalid-component-name` otherwise).
+- **A `@pathServer` is for a path item, not an operation**: `get` and `post`
+  of one route share it. The same server on several operations of one path is
+  written once; one URL with a different description or variables on another
+  is the error `path-server-conflict`, and the first is the one emitted.
+- **Server variables** are `@server`'s third parameter: each property is a
+  variable, its default the variable's `default` (`""` without one), its
+  `@doc` the `description`, and a literal, enum or union of literals type its
+  `enum`. As with `@server`, a variable is a string (a string, a string enum
+  or a union of strings: `path-server-invalid-variable` otherwise), and each
+  `{name}` of the URL needs its property (`path-server-missing-variable`).
+
+  ```tsp
+  @route("/jmap")
+  @pathServer("{origin}{basePath}", "Mail", {
+    @doc("The mail origin") origin: string = "https://mail.example.com",
+    @doc("Where it is mounted") basePath: string = "/jmap",
+  })
+  @get op session(): string;
+  ```
+
+  ```yaml
+  /jmap:
+    servers:
+      - url: '{origin}{basePath}'
+        description: Mail
+        variables:
+          origin:
+            default: https://mail.example.com
+            description: The mail origin
+          basePath:
+            default: /jmap
+            description: Where it is mounted
+  ```
+- **Several services** keep their own: each decorator marks the object the
+  emitter writes for its own operation or header, and the emitter reads and
+  takes off those marks per document, so the same path in two services, a
+  dotted service name or a nested service never mixes them.
+- **Operations of a `@sharedRoute`** merge into one in the document; their
+  servers add up, and each one's shared responses are hoisted.
+- **`@typespec/versioning` is not verified.** A shared response is marked on
+  the operation at emit time, and nothing here tests a versioned service,
+  whose operations the versioning library clones: shared responses on a
+  versioned service may stay inline, and a `@pathServer`'s servers may be missing.
+- **Nothing changes without them.** A spec that uses none of the three emits
+  byte-identical output, and the hoisting is the same in 3.1 and 3.2.
+- `@nxgt/openapi-codegen` generates a document with `$ref` responses and
+  headers as it does the inline copies.
+
 ## What follows downstream
 
 | Step | What it does with the `query` operation |

package/docs/roadmap.md

@@ -25,6 +25,14 @@ Nothing planned beyond what is under Later.
 
 ## Shipped
 
+### 0.14.0
+
+- **Shared responses, shared headers and path servers.** `@sharedResponse`
+  and `@sharedHeader` emit a response and a header once under
+  `components.responses` and `components.headers`, a `$ref` at each use, and
+  `@pathServer` puts `servers` on one path item, from the spec alone with no
+  post-processing, with `@server`'s variables.
+
 ### 0.13.2
 
 - **Exact scalar rules in the generated code.** `@nxgt/openapi-codegen`

package/docs/troubleshooting.md

@@ -361,6 +361,98 @@ options:
     openapi-versions: ['3.2.0']
 ```
 
+## `The server URL https://{tenant}.example.com of listUsers has {tenant}, which is not a property of its parameters. Add the variable, or take the braces out.`
+
+**When:** `tsp compile`; the error `path-server-missing-variable` on a
+`@pathServer` whose URL has a `{name}` its third parameter lacks.
+
+**Fix:** add the variable, as `@server` asks:
+
+```tsp
+@pathServer("https://{tenant}.example.com", "Tenant", { tenant: string = "main" })
+```
+
+## `The variable port of the @pathServer of listUsers is not a string, a string enum or a union of strings: an OpenAPI server variable is a string.`
+
+**When:** `tsp compile`; the error `path-server-invalid-variable`, for a
+variable typed `int32`, `boolean`… The default of a server variable is a string.
+
+**Fix:** type it as a string: `port: string = "443"`, or `"443" | "8443"`.
+
+## `Trace is marked @sharedHeader outside a response header: it applies to a @header of a reply only, not to a request header or a body property.`
+
+**When:** `tsp compile`; the error `shared-header-misplaced`, for a
+`@sharedHeader` property that ends up in a request (a `@header` parameter) or
+in a body schema.
+
+**Why:** `components.headers` holds response headers; a request header is a
+parameter and a body property is a schema.
+
+**Fix:** take `@sharedHeader` off, or keep it on a `@header` of a reply model.
+
+## `Operations sharing the route GET /m reply 400 with different responses, one of them a @sharedResponse: @sharedRoute merges them into one reply, which cannot be a component. Give them the same shared response, or none.`
+
+**When:** `tsp compile`; the error `shared-response-merged`, for operations
+with `@sharedRoute` that answer one status with different responses (two shared
+ones of different names, or a shared one and a plain one).
+
+**Why:** the operations are one in the document, with one reply per status,
+which cannot be a component and something else.
+
+**Fix:** answer that status with the same `@sharedResponse` in each, or with
+none:
+
+```tsp
+@route("/m") @sharedRoute @get op one(): string | Gone;
+@route("/m") @sharedRoute @get op two(): string | Gone;
+```
+
+## `Two shared responses named Failure differ: a component is emitted once. Give each its own name, or make them the same.`
+
+**When:** `tsp compile`; the error `shared-component-conflict`, for two
+`@sharedResponse` models (or two `@sharedHeader` properties, as `headers`) that
+take one name and do not emit the same response or header.
+
+**Why:** a component has one definition, and the emitter will not pick one.
+The first is the component; the other stays inline in the document.
+
+**Fix:** give each its own name, or make them one model:
+
+```tsp
+@sharedResponse("BadInput") @error model A { @statusCode code: 400; a: string; }
+@sharedResponse("Refused") @error model B { @statusCode code: 400; b: string; }
+```
+
+## `Two @pathServer of /users give the server https://a.example.com a description or variables that differ. Give the path one definition of it.`
+
+**When:** `tsp compile`; the error `path-server-conflict`. The first definition is emitted.
+
+**Why:** operations of one path share its `servers`; the same URL cannot be
+described two ways. The first definition is the one emitted.
+
+**Fix:** give every `@pathServer` of that URL on the path the same
+description and variables, or put it on one operation.
+
+## `"not ok" is not a name OpenAPI allows for a component: use letters, digits, '.', '_' and '-'.`
+
+**When:** `tsp compile`; the error `invalid-component-name`, on a name given to
+`@sharedResponse` or `@sharedHeader` (or a model or property name used as one).
+
+**Fix:** pass a name of letters, digits, `.`, `_` and `-`:
+`@sharedResponse("NotOk")`.
+
+## `Unauthorized is marked @sharedResponse: emit with @nxgt/typespec, which writes it; @typespec/openapi3 would write it inline or drop it.`
+
+**When:** `tsp compile` with `@typespec/openapi3` in `emit`; the error
+`shared-needs-nxgt-emitter` for each `@sharedResponse`, `@sharedHeader` and
+`@pathServer`.
+
+**Why:** only the emitter `@nxgt/typespec` reads them: `@typespec/openapi3`
+would write the copies, leak `x-nxgt-component` on a header, or leave out the
+path's `servers`.
+
+**Fix:** emit with `@nxgt/typespec` ([The emitter](guide/emitter.md)).
+
 ## `The emitter @nxgt/typespec runs @typespec/openapi3, which is not installed: add it beside @nxgt/typespec.`
 
 **When:** `tsp compile` with `@nxgt/typespec` in `emit`; the error

package/lib/components.tsp

@@ -0,0 +1,65 @@
+import "../dist/index.js";
+
+using TypeSpec.Reflection;
+
+namespace Nxgt;
+
+/**
+ * Emits a response model once, under `components.responses`, with a `$ref`
+ * at each operation that returns it, instead of a full copy at each. The
+ * name is the model's unless one is given. Two shared responses of one name
+ * that differ are the error `shared-component-conflict`. Only
+ * `@nxgt/typespec` writes it: `@typespec/openapi3` would write the copies.
+ *
+ * @example
+ * ```typespec
+ * @sharedResponse
+ * @error model Unauthorized { @statusCode code: 401; message: string; }
+ * ```
+ */
+extern dec sharedResponse(target: Model, name?: valueof string);
+
+/**
+ * Emits a response header once, under `components.headers`, with a `$ref`
+ * at each response that carries it. The name is the property's unless one is
+ * given. For a response header only; a request header is a parameter.
+ *
+ * @example
+ * ```typespec
+ * model NoStore {
+ *   @sharedHeader("NoStore") @header("cache-control") cacheControl: "no-store";
+ * }
+ * ```
+ */
+extern dec sharedHeader(target: ModelProperty, name?: valueof string);
+
+/**
+ * Puts `servers` on the path item of the operation: the other paths keep the
+ * document's. Repeated on the operations of one path, the servers add up; the
+ * same server twice is one, and one URL with two different definitions is the
+ * error `path-server-conflict`. The third parameter is `@server`'s: each
+ * property is a variable of the URL, its default the variable's `default`
+ * and its doc comment the `description`.
+ *
+ * @param url The server's URL, with `{variable}` placeholders if any.
+ * @param description What the server is.
+ * @param parameters The URL's variables.
+ *
+ * @example
+ * ```typespec
+ * @route("/files")
+ * @pathServer("{origin}{basePath}", "Files", {
+ *   @doc("The server's origin")
+ *   origin: string = "https://files.example.com",
+ *   @doc("Where the API is mounted")
+ *   basePath: string = "/files",
+ * })
+ * @get op listFiles(): string[];
+ * ```
+ */
+extern dec pathServer(
+  target: Operation,
+  url: valueof string,
+  description?: valueof string,
+  parameters?: Record<unknown>
+);

package/lib/main.tsp

@@ -11,3 +11,4 @@ import "./headers.tsp";
 import "./sorting.tsp";
 import "./requests.tsp";
 import "./query-method.tsp";
+import "./components.tsp";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.13.2",
+	"version": "0.14.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -61,7 +61,7 @@
 		}
 	},
 	"devDependencies": {
-		"@nxgt/openapi-codegen": "^0.10.0",
+		"@nxgt/openapi-codegen": "^0.11.0",
 		"@nxgt/openapi-hono": "^0.3.3",
 		"@nxgt/zod": "^0.1.3",
 		"@types/bun": "^1.4.0",