@typespec/openapi 0.41.0

package/README.md

@@ -0,0 +1,105 @@
+# TypeSpec OpenAPI Library
+
+This package provide [TypeSpec](https://github.com/microsoft/typespec) decorators to specify some OpenAPI specific concepts.
+
+## Install
+
+In your typespec project root
+
+```bash
+npm install @typespec/openapi
+```
+
+## Usage
+
+```typespec
+import "@typespec/openapi";
+
+using OpenAPI;
+```
+
+## References
+
+Decorators:
+
+- [`@defaultResponse`](#defaultResponse)
+- [`@extension`](#extension)
+- [`@externalDocs`](#externalDocs)
+- [`@operationId`](#operationId)
+
+### `@defaultResponse`
+
+**IMPORTANT This is to be used on `NON-ERROR` responses that cover all the other status codes. If you are looking to represent an error use [`@error`](https://microsoft.github.io/typespec/docs/standard-library/built-in-decorators/#error)**
+
+Decorator that can be used on a response model to specify the `default` status code that OpenAPI allow.
+
+```typespec
+@defaultResponse
+model MyNonErrorResponse {}
+
+op foo(): MyNonErrorResponse;
+```
+
+### `@extension`
+
+This decorator lets you specify custom key(starting with `x-`) value pair that will be added to the OpenAPI document.
+[OpenAPI reference on extensions](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#specificationExtensions)
+
+Arguments:
+
+| Name    | foo          | Description                                                      |
+| ------- | ------------ | ---------------------------------------------------------------- |
+| `key`   | **Required** | Extension key. **MUST** start with `x-`                          |
+| `value` | **Required** | Value of the extension. Can be an primitive, a tuple or a model. |
+
+```typespec
+@extension("x-custom", "MyCustomValue")
+model Foo {}
+
+// Value can be an model.
+@extension(
+  "x-custom",
+  {
+    some: "value",
+  }
+)
+model Foo {}
+```
+
+### `@externalDocs`
+
+Decorator that can be used to provide the `externalDocs` property on OpenAPI elements.
+[OpenAPI spec for externalDocs](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#externalDocumentationObject)
+
+Arguments:
+
+| Name          | foo          | Description                      |
+| ------------- | ------------ | -------------------------------- |
+| `url`         | **Required** | Url for the external docs        |
+| `description` | **Optional** | Description of the documentation |
+
+```typespec
+@externalDocs("https://example.com", "More info there")
+model Foo {}
+```
+
+### `@operationId`
+
+Decorator that can be used on an operation to specify the `operationId` field in OpenAPI. If this is not provided the `operationId` will be the typespec operation name.
+
+Arguments:
+
+| Name   | foo          | Description         |
+| ------ | ------------ | ------------------- |
+| `opId` | **Required** | Id of the operation |
+
+```typespec
+@operationId("custom_Foo")
+op foo(): string;
+```
+
+## See also
+
+- [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
+- [TypeSpec Website](https://microsoft.github.io/typespec)
+- [TypeSpec for the OpenAPI Developer](https://github.com/microsoft/typespec/blob/main/docs/typespec-for-openapi-dev.md)

package/dist/src/decorators.d.ts

@@ -0,0 +1,37 @@
+import { DecoratorContext, Model, Operation, Program, Type, TypeSpecValue } from "@typespec/compiler";
+import { ExtensionKey } from "./types.js";
+export declare const namespace = "OpenAPI";
+/**
+ * Set a specific operation ID.
+ * @param context Decorator Context
+ * @param entity Decorator target
+ * @param opId Operation ID.
+ */
+export declare function $operationId(context: DecoratorContext, entity: Operation, opId: string): void;
+/**
+ * @returns operationId set via the @operationId decorator or `undefined`
+ */
+export declare function getOperationId(program: Program, entity: Operation): string | undefined;
+export declare function $extension(context: DecoratorContext, entity: Type, extensionName: string, value: TypeSpecValue): void;
+export declare function setExtension(program: Program, entity: Type, extensionName: ExtensionKey, data: unknown): void;
+export declare function getExtensions(program: Program, entity: Type): ReadonlyMap<ExtensionKey, any>;
+export declare function $defaultResponse(context: DecoratorContext, entity: Model): void;
+/**
+ * Check if the given model has been mark as a default response.
+ * @param program TypeSpec Program
+ * @param entity Model to check.
+ * @returns boolean.
+ */
+export declare function isDefaultResponse(program: Program, entity: Type): boolean;
+export interface ExternalDocs {
+    url: string;
+    description?: string;
+}
+/**
+ * Allows referencing an external resource for extended documentation.
+ * @param url The URL for the target documentation. Value MUST be in the format of a URL.
+ * @param @optional description A short description of the target documentation.
+ */
+export declare function $externalDocs(context: DecoratorContext, target: Type, url: string, description?: string): void;
+export declare function getExternalDocs(program: Program, entity: Type): ExternalDocs | undefined;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/src/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,EACL,SAAS,EACT,OAAO,EACP,IAAI,EAEJ,aAAa,EACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,SAAS,YAAY,CAAC;AAGnC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,QAEtF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAEtF;AAID,wBAAgB,UAAU,CACxB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,IAAI,EACZ,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,QAerB;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,IAAI,EACZ,aAAa,EAAE,YAAY,EAC3B,IAAI,EAAE,OAAO,QAOd;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAG,WAAW,CAAC,YAAY,EAAE,GAAG,CAAC,CAE5F;AAYD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,QAGxE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAEzE;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAGD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,IAAI,EACZ,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,QAOrB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAG,YAAY,GAAG,SAAS,CAExF"}

package/dist/src/decorators.js

@@ -0,0 +1,85 @@
+import { typespecTypeToJson, } from "@typespec/compiler";
+import { setStatusCode } from "@typespec/http";
+import { createStateSymbol, reportDiagnostic } from "./lib.js";
+export const namespace = "OpenAPI";
+const operationIdsKey = createStateSymbol("operationIds");
+/**
+ * Set a specific operation ID.
+ * @param context Decorator Context
+ * @param entity Decorator target
+ * @param opId Operation ID.
+ */
+export function $operationId(context, entity, opId) {
+    context.program.stateMap(operationIdsKey).set(entity, opId);
+}
+/**
+ * @returns operationId set via the @operationId decorator or `undefined`
+ */
+export function getOperationId(program, entity) {
+    return program.stateMap(operationIdsKey).get(entity);
+}
+const openApiExtensionKey = createStateSymbol("openApiExtension");
+export function $extension(context, entity, extensionName, value) {
+    if (!isOpenAPIExtensionKey(extensionName)) {
+        reportDiagnostic(context.program, {
+            code: "invalid-extension-key",
+            format: { value: extensionName },
+            target: entity,
+        });
+    }
+    const [data, diagnostics] = typespecTypeToJson(value, entity);
+    if (diagnostics.length > 0) {
+        context.program.reportDiagnostics(diagnostics);
+    }
+    setExtension(context.program, entity, extensionName, data);
+}
+export function setExtension(program, entity, extensionName, data) {
+    var _a;
+    const openApiExtensions = program.stateMap(openApiExtensionKey);
+    const typeExtensions = (_a = openApiExtensions.get(entity)) !== null && _a !== void 0 ? _a : new Map();
+    typeExtensions.set(extensionName, data);
+    openApiExtensions.set(entity, typeExtensions);
+}
+export function getExtensions(program, entity) {
+    var _a;
+    return (_a = program.stateMap(openApiExtensionKey).get(entity)) !== null && _a !== void 0 ? _a : new Map();
+}
+function isOpenAPIExtensionKey(key) {
+    return key.startsWith("x-");
+}
+/**
+ * The @defaultResponse decorator can be applied to a model. When that model is used
+ * as the return type of an operation, this return type will be the default response.
+ *
+ */
+const defaultResponseKey = createStateSymbol("defaultResponse");
+export function $defaultResponse(context, entity) {
+    setStatusCode(context.program, entity, ["*"]);
+    context.program.stateSet(defaultResponseKey).add(entity);
+}
+/**
+ * Check if the given model has been mark as a default response.
+ * @param program TypeSpec Program
+ * @param entity Model to check.
+ * @returns boolean.
+ */
+export function isDefaultResponse(program, entity) {
+    return program.stateSet(defaultResponseKey).has(entity);
+}
+const externalDocsKey = createStateSymbol("externalDocs");
+/**
+ * Allows referencing an external resource for extended documentation.
+ * @param url The URL for the target documentation. Value MUST be in the format of a URL.
+ * @param @optional description A short description of the target documentation.
+ */
+export function $externalDocs(context, target, url, description) {
+    const doc = { url };
+    if (description) {
+        doc.description = description;
+    }
+    context.program.stateMap(externalDocsKey).set(target, doc);
+}
+export function getExternalDocs(program, entity) {
+    return program.stateMap(externalDocsKey).get(entity);
+}
+//# sourceMappingURL=decorators.js.map

package/dist/src/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/decorators.ts"],"names":[],"mappings":"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"}

package/dist/src/helpers.d.ts

@@ -0,0 +1,50 @@
+import { ModelProperty, Operation, Program, Type, TypeNameOptions } from "@typespec/compiler";
+/**
+ * Determines whether a type will be inlined in OpenAPI rather than defined
+ * as a schema and referenced.
+ *
+ * All anonymous types (anonymous models, arrays, tuples, etc.) are inlined.
+ *
+ * Template instantiations are inlined unless they have a friendly name.
+ *
+ * A friendly name can be provided by the user using `@friendlyName`
+ * decorator, or chosen by default in simple cases.
+ */
+export declare function shouldInline(program: Program, type: Type): boolean;
+/**
+ * Gets the name of a type to be used in OpenAPI.
+ *
+ * For inlined types: this is the TypeSpec-native name written to `x-typespec-name`.
+ *
+ * For non-inlined types: this is either the friendly name or the TypeSpec-native name.
+ *
+ * TypeSpec-native names are shortened to exclude root `TypeSpec` namespace and service
+ * namespace using the provided `TypeNameOptions`.
+ */
+export declare function getOpenAPITypeName(program: Program, type: Type, options: TypeNameOptions, existing?: Record<string, any>): string;
+export declare function checkDuplicateTypeName(program: Program, type: Type, name: string, existing: Record<string, unknown> | undefined): void;
+/**
+ * Gets the key that is used to define a parameter in OpenAPI.
+ */
+export declare function getParameterKey(program: Program, property: ModelProperty, newParam: unknown, existingParams: Record<string, unknown>, options: TypeNameOptions): string;
+/**
+ * Resolve the OpenAPI operation ID for the given operation using the following logic:
+ * - If @operationId was specified use that value
+ * - If operation is defined at the root or under the service namespace return `<operation.name>`
+ * - Otherwise(operation is under another namespace or interface) return `<namespace/interface.name>_<operation.name>`
+ *
+ * @param program TypeSpec Program
+ * @param operation Operation
+ * @returns Operation ID in this format `<name>` or `<group>_<name>`
+ */
+export declare function resolveOperationId(program: Program, operation: Operation): string;
+/**
+ * Determines if a property is read-only, which is defined as being
+ * decorated `@visibility("read")`.
+ *
+ * If there is more than 1 `@visibility` argument, then the property is not
+ * read-only. For example, `@visibility("read", "update")` does not
+ * designate a read-only property.
+ */
+export declare function isReadonlyProperty(program: Program, property: ModelProperty): boolean;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,aAAa,EACb,SAAS,EACT,OAAO,EACP,IAAI,EACJ,eAAe,EAChB,MAAM,oBAAoB,CAAC;AAI5B;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAelE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,eAAe,EACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,MAAM,CAKR;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,QAW9C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,OAAO,EACjB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,OAAO,EAAE,eAAe,GACvB,MAAM,CAoBR;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,UAmBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,WAK3E"}

package/dist/src/helpers.js

@@ -0,0 +1,119 @@
+import { getFriendlyName, getTypeName, getVisibility, isGlobalNamespace, isService, isTemplateInstance, } from "@typespec/compiler";
+import { getOperationId } from "./decorators.js";
+import { reportDiagnostic } from "./lib.js";
+/**
+ * Determines whether a type will be inlined in OpenAPI rather than defined
+ * as a schema and referenced.
+ *
+ * All anonymous types (anonymous models, arrays, tuples, etc.) are inlined.
+ *
+ * Template instantiations are inlined unless they have a friendly name.
+ *
+ * A friendly name can be provided by the user using `@friendlyName`
+ * decorator, or chosen by default in simple cases.
+ */
+export function shouldInline(program, type) {
+    if (getFriendlyName(program, type)) {
+        return false;
+    }
+    switch (type.kind) {
+        case "Model":
+            return !type.name || isTemplateInstance(type);
+        case "Scalar":
+            return program.checker.isStdType(type) || isTemplateInstance(type);
+        case "Enum":
+        case "Union":
+            return !type.name;
+        default:
+            return true;
+    }
+}
+/**
+ * Gets the name of a type to be used in OpenAPI.
+ *
+ * For inlined types: this is the TypeSpec-native name written to `x-typespec-name`.
+ *
+ * For non-inlined types: this is either the friendly name or the TypeSpec-native name.
+ *
+ * TypeSpec-native names are shortened to exclude root `TypeSpec` namespace and service
+ * namespace using the provided `TypeNameOptions`.
+ */
+export function getOpenAPITypeName(program, type, options, existing) {
+    var _a;
+    const name = (_a = getFriendlyName(program, type)) !== null && _a !== void 0 ? _a : getTypeName(type, options);
+    checkDuplicateTypeName(program, type, name, existing);
+    return name;
+}
+export function checkDuplicateTypeName(program, type, name, existing) {
+    if (existing && existing[name]) {
+        reportDiagnostic(program, {
+            code: "duplicate-type-name",
+            format: {
+                value: name,
+            },
+            target: type,
+        });
+    }
+}
+/**
+ * Gets the key that is used to define a parameter in OpenAPI.
+ */
+export function getParameterKey(program, property, newParam, existingParams, options) {
+    const parent = property.model;
+    let key = getOpenAPITypeName(program, parent, options);
+    if (parent.properties.size > 1) {
+        key += `.${property.name}`;
+    }
+    if (existingParams[key]) {
+        reportDiagnostic(program, {
+            code: "duplicate-type-name",
+            messageId: "parameter",
+            format: {
+                value: key,
+            },
+            target: property,
+        });
+    }
+    return key;
+}
+/**
+ * Resolve the OpenAPI operation ID for the given operation using the following logic:
+ * - If @operationId was specified use that value
+ * - If operation is defined at the root or under the service namespace return `<operation.name>`
+ * - Otherwise(operation is under another namespace or interface) return `<namespace/interface.name>_<operation.name>`
+ *
+ * @param program TypeSpec Program
+ * @param operation Operation
+ * @returns Operation ID in this format `<name>` or `<group>_<name>`
+ */
+export function resolveOperationId(program, operation) {
+    const explicitOperationId = getOperationId(program, operation);
+    if (explicitOperationId) {
+        return explicitOperationId;
+    }
+    if (operation.interface) {
+        return `${operation.interface.name}_${operation.name}`;
+    }
+    const namespace = operation.namespace;
+    if (namespace === undefined ||
+        isGlobalNamespace(program, namespace) ||
+        isService(program, namespace)) {
+        return operation.name;
+    }
+    return `${namespace.name}_${operation.name}`;
+}
+/**
+ * Determines if a property is read-only, which is defined as being
+ * decorated `@visibility("read")`.
+ *
+ * If there is more than 1 `@visibility` argument, then the property is not
+ * read-only. For example, `@visibility("read", "update")` does not
+ * designate a read-only property.
+ */
+export function isReadonlyProperty(program, property) {
+    const visibility = getVisibility(program, property);
+    // note: multiple visibilities that include read are not handled using
+    // readonly: true, but using separate schemas.
+    return (visibility === null || visibility === void 0 ? void 0 : visibility.length) === 1 && visibility[0] === "read";
+}
+//# sourceMappingURL=helpers.js.map

package/dist/src/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./decorators.js";
+export * from "./helpers.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export * from "./decorators.js";
+export * from "./helpers.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/src/lib.d.ts

@@ -0,0 +1,36 @@
+export declare const libDef: {
+    readonly name: "@typespec/openapi";
+    readonly diagnostics: {
+        readonly "invalid-extension-key": {
+            readonly severity: "error";
+            readonly messages: {
+                readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+            };
+        };
+        readonly "duplicate-type-name": {
+            readonly severity: "error";
+            readonly messages: {
+                readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+                readonly parameter: import("@typespec/compiler").CallableMessage<["value"]>;
+            };
+        };
+    };
+};
+export declare const reportDiagnostic: <C extends "invalid-extension-key" | "duplicate-type-name", M extends keyof {
+    "invalid-extension-key": {
+        readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+    };
+    "duplicate-type-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+        readonly parameter: import("@typespec/compiler").CallableMessage<["value"]>;
+    };
+}[C]>(program: import("@typespec/compiler").Program, diag: import("@typespec/compiler").DiagnosticReport<{
+    "invalid-extension-key": {
+        readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+    };
+    "duplicate-type-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["value"]>;
+        readonly parameter: import("@typespec/compiler").CallableMessage<["value"]>;
+    };
+}, C, M>) => void, createStateSymbol: (name: string) => symbol;
+//# sourceMappingURL=lib.d.ts.map

package/dist/src/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;CAiBT,CAAC;AACX,eAAO,MAAQ,gBAAgB;;;;;;;;;;;;;;;;mBAAE,iBAAiB,0BAAkC,CAAC"}

package/dist/src/lib.js

@@ -0,0 +1,21 @@
+import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
+export const libDef = {
+    name: "@typespec/openapi",
+    diagnostics: {
+        "invalid-extension-key": {
+            severity: "error",
+            messages: {
+                default: paramMessage `OpenAPI extension must start with 'x-' but was '${"value"}'`,
+            },
+        },
+        "duplicate-type-name": {
+            severity: "error",
+            messages: {
+                default: paramMessage `Duplicate type name: '${"value"}'. Check @friendlyName decorators and overlap with types in TypeSpec or service namespace.`,
+                parameter: paramMessage `Duplicate parameter key: '${"value"}'. Check @friendlyName decorators and overlap with types in TypeSpec or service namespace.`,
+            },
+        },
+    },
+};
+export const { reportDiagnostic, createStateSymbol } = createTypeSpecLibrary(libDef);
+//# sourceMappingURL=lib.js.map

package/dist/src/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE,mBAAmB;IACzB,WAAW,EAAE;QACX,uBAAuB,EAAE;YACvB,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE;gBACR,OAAO,EAAE,YAAY,CAAA,mDAAmD,OAAO,GAAG;aACnF;SACF;QACD,qBAAqB,EAAE;YACrB,QAAQ,EAAE,OAAO;YACjB,QAAQ,EAAE;gBACR,OAAO,EAAE,YAAY,CAAA,yBAAyB,OAAO,4FAA4F;gBACjJ,SAAS,EAAE,YAAY,CAAA,6BAA6B,OAAO,4FAA4F;aACxJ;SACF;KACF;CACO,CAAC;AACX,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC"}

package/dist/src/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { TypeSpecTestLibrary } from "@typespec/compiler/testing";
+export declare const OpenAPITestLibrary: TypeSpecTestLibrary;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGpF,eAAO,MAAM,kBAAkB,EAAE,mBAG/B,CAAC"}

package/dist/src/testing/index.js

@@ -0,0 +1,8 @@
+import { resolvePath } from "@typespec/compiler";
+import { createTestLibrary } from "@typespec/compiler/testing";
+import { fileURLToPath } from "url";
+export const OpenAPITestLibrary = createTestLibrary({
+    name: "@typespec/openapi",
+    packageRoot: resolvePath(fileURLToPath(import.meta.url), "../../../../"),
+});
+//# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAuB,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,CAAC,MAAM,kBAAkB,GAAwB,iBAAiB,CAAC;IACvE,IAAI,EAAE,mBAAmB;IACzB,WAAW,EAAE,WAAW,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,cAAc,CAAC;CACzE,CAAC,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,2 @@
+export type ExtensionKey = `x-${string}`;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,KAAK,MAAM,EAAE,CAAC"}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/lib/decorators.tsp

@@ -0,0 +1,62 @@
+using TypeSpec.Reflection;
+
+namespace OpenAPI;
+
+/**
+ * Specify the OpenAPI `operationId` property for this operation.
+ *
+ * @param operationId Operation id value.
+ *
+ * @example
+ *
+ * ```typespec
+ * @operationId("download")
+ * op read(): string;
+ * ```
+ */
+extern dec operationId(target: Operation, operationId: string);
+
+/**
+ * Attach some custom data to the OpenAPI element generated from this type.
+ *
+ * @param key Extension key. Must start with `x-`
+ * @param value Extension value.
+ *
+ * @example
+ *
+ * ```typespec
+ * @extension("x-custom", "My value")
+ * @extension("x-pageable", {nextLink: "x-next-link"})
+ * op read(): string;
+ * ```
+ */
+extern dec extension(target: unknown, key: string, value: unknown);
+
+/**
+ * Specify that this model is to be treated as the OpenAPI `default` response.
+ * This differs from the compiler built-in `@error` decorator as this does not necessarily represent an error.
+ *
+ * @example
+ *
+ * ```typespec
+ * @defaultResponse
+ * model PetStoreResponse is object;
+ *
+ * op listPets(): Pet[] | PetStoreResponse;
+ * ```
+ */
+extern dec defaultResponse(target: object);
+
+/**
+ * Specify the OpenAPI `externalDocs` property for this type.
+ *
+ * @param url Url to the docs
+ * @param description Description of the docs
+ *
+ * @example
+ * ```typespec
+ * @externalDocs("https://example.com/detailed.md", "Detailed information on how to use this operation")
+ * op listPets(): Pet[];
+ * ```
+ */
+extern dec externalDocs(target: unknown, url: string, description?: string);

package/lib/main.tsp

@@ -0,0 +1,2 @@
+import "../dist/src/index.js";
+import "./decorators.tsp";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@typespec/openapi",
+  "version": "0.41.0",
+  "author": "Microsoft Corporation",
+  "description": "TypeSpec library providing OpenAPI concepts",
+  "homepage": "https://microsoft.github.io/typespec",
+  "readme": "https://github.com/Azure/typespec/blob/master/README.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Azure/typespec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Azure/typespec/issues"
+  },
+  "keywords": [
+    "typespec"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
+  "tspMain": "lib/main.tsp",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./testing": "./dist/src/testing/index.js"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/src/index.d.ts"
+      ],
+      "testing": [
+        "./dist/src/testing/index.d.ts"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "lib/*.tsp",
+    "dist/**",
+    "!dist/test/**"
+  ],
+  "peerDependencies": {
+    "@typespec/compiler": "~0.41.0",
+    "@typespec/http": "~0.41.0",
+    "@typespec/rest": "~0.41.0"
+  },
+  "devDependencies": {
+    "@types/mocha": "~10.0.0",
+    "@types/node": "~18.11.9",
+    "@typespec/compiler": "~0.41.0",
+    "@typespec/http": "~0.41.0",
+    "@typespec/rest": "~0.41.0",
+    "@typespec/eslint-config-typespec": "~0.6.0",
+    "@typespec/library-linter": "~0.41.0",
+    "@typespec/eslint-plugin": "~0.41.0",
+    "eslint": "^8.12.0",
+    "mocha": "~10.1.0",
+    "mocha-junit-reporter": "~2.2.0",
+    "mocha-multi-reporters": "~1.5.1",
+    "c8": "~7.12.0",
+    "rimraf": "~3.0.2",
+    "typescript": "~4.9.3"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist ./temp",
+    "build": "tsc -p . && npm run lint-typespec-library",
+    "watch": "tsc -p . --watch",
+    "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
+    "test": "mocha",
+    "test-official": "c8 mocha --forbid-only --reporter mocha-multi-reporters",
+    "lint": "eslint . --ext .ts --max-warnings=0",
+    "lint:fix": "eslint . --fix --ext .ts"
+  }
+}