Change OpenAPI namespace to TypeSpec.OpenAPI (#2439)

Fixes #2351. This is a breaking change. **TODO** - [x] typespec-azure companion PR: https://github.com/Azure/typespec-azure/pull/3599
microsoft · Sep 19, 2023 · 681cf10 · 681cf10
1 parent 6e5b050
commit 681cf10
Show file tree

Hide file tree

Showing 21 changed files with 84 additions and 63 deletions.
diff --git a/common/changes/@typespec/openapi/openApi-FixNamespace_2023-09-19-19-48.json b/common/changes/@typespec/openapi/openApi-FixNamespace_2023-09-19-19-48.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi",
+      "comment": "Changed namespace from `OpenAPI` to `TypeSpec.OpenAPI`.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi"
+}
diff --git a/common/changes/@typespec/openapi3/openApi-FixNamespace_2023-09-19-17-16.json b/common/changes/@typespec/openapi3/openApi-FixNamespace_2023-09-19-17-16.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi3",
+      "comment": "Fix `OpenAPI` namespace to be `TypeSpec.OpenAPI`.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi3"
+}
diff --git a/docs/standard-library/openapi/reference/data-types.md b/docs/standard-library/openapi/reference/data-types.md
@@ -6,28 +6,28 @@ toc_max_heading_level: 3
 
 # Data types
 
-## OpenAPI
+## TypeSpec.OpenAPI
 
-### `AdditionalInfo` {#OpenAPI.AdditionalInfo}
+### `AdditionalInfo` {#TypeSpec.OpenAPI.AdditionalInfo}
 
 Additional information for the OpenAPI document.
 
 ```typespec
-model OpenAPI.AdditionalInfo
+model TypeSpec.OpenAPI.AdditionalInfo
 ```
 
-### `Contact` {#OpenAPI.Contact}
+### `Contact` {#TypeSpec.OpenAPI.Contact}
 
 Contact information for the exposed API.
 
 ```typespec
-model OpenAPI.Contact
+model TypeSpec.OpenAPI.Contact
 ```
 
-### `License` {#OpenAPI.License}
+### `License` {#TypeSpec.OpenAPI.License}
 
 License information for the exposed API.
 
 ```typespec
-model OpenAPI.License
+model TypeSpec.OpenAPI.License
 ```
diff --git a/docs/standard-library/openapi/reference/decorators.md b/docs/standard-library/openapi/reference/decorators.md
@@ -6,15 +6,15 @@ toc_max_heading_level: 3
 
 # Decorators
 
-## OpenAPI
+## TypeSpec.OpenAPI
 
-### `@defaultResponse` {#@OpenAPI.defaultResponse}
+### `@defaultResponse` {#@TypeSpec.OpenAPI.defaultResponse}
 
 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.
 
 ```typespec
-@OpenAPI.defaultResponse
+@TypeSpec.OpenAPI.defaultResponse
 ```
 
 #### Target
@@ -34,12 +34,12 @@ model PetStoreResponse is object;
 op listPets(): Pet[] | PetStoreResponse;
 ```
 
-### `@extension` {#@OpenAPI.extension}
+### `@extension` {#@TypeSpec.OpenAPI.extension}
 
 Attach some custom data to the OpenAPI element generated from this type.
 
 ```typespec
-@OpenAPI.extension(key: valueof string, value: unknown)
+@TypeSpec.OpenAPI.extension(key: valueof string, value: unknown)
 ```
 
 #### Target
@@ -66,12 +66,12 @@ Attach some custom data to the OpenAPI element generated from this type.
 op read(): string;
 ```
 
-### `@externalDocs` {#@OpenAPI.externalDocs}
+### `@externalDocs` {#@TypeSpec.OpenAPI.externalDocs}
 
 Specify the OpenAPI `externalDocs` property for this type.
 
 ```typespec
-@OpenAPI.externalDocs(url: valueof string, description?: valueof string)
+@TypeSpec.OpenAPI.externalDocs(url: valueof string, description?: valueof string)
 ```
 
 #### Target
@@ -95,13 +95,13 @@ Specify the OpenAPI `externalDocs` property for this type.
 op listPets(): Pet[];
 ```
 
-### `@info` {#@OpenAPI.info}
+### `@info` {#@TypeSpec.OpenAPI.info}
 
 Specify OpenAPI additional information.
 The service `title` and `version` are already specified using `@service`.
 
 ```typespec
-@OpenAPI.info(additionalInfo: OpenAPI.AdditionalInfo)
+@TypeSpec.OpenAPI.info(additionalInfo: TypeSpec.OpenAPI.AdditionalInfo)
 ```
 
 #### Target
@@ -110,16 +110,16 @@ The service `title` and `version` are already specified using `@service`.
 
 #### Parameters
 
-| Name           | Type                           | Description            |
-| -------------- | ------------------------------ | ---------------------- |
-| additionalInfo | `model OpenAPI.AdditionalInfo` | Additional information |
+| Name           | Type                                    | Description            |
+| -------------- | --------------------------------------- | ---------------------- |
+| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information |
 
-### `@operationId` {#@OpenAPI.operationId}
+### `@operationId` {#@TypeSpec.OpenAPI.operationId}
 
 Specify the OpenAPI `operationId` property for this operation.
 
 ```typespec
-@OpenAPI.operationId(operationId: valueof string)
+@TypeSpec.OpenAPI.operationId(operationId: valueof string)
 ```
 
 #### Target

diff --git a/docs/standard-library/openapi/reference/index.md b/docs/standard-library/openapi/reference/index.md
@@ -31,18 +31,18 @@ npm install --save-peer @typespec/openapi
 </TabItem>
 </Tabs>
 
-## OpenAPI
+## TypeSpec.OpenAPI
 
 ### Decorators
 
-- [`@defaultResponse`](./decorators.md#@OpenAPI.defaultResponse)
-- [`@extension`](./decorators.md#@OpenAPI.extension)
-- [`@externalDocs`](./decorators.md#@OpenAPI.externalDocs)
-- [`@info`](./decorators.md#@OpenAPI.info)
-- [`@operationId`](./decorators.md#@OpenAPI.operationId)
+- [`@defaultResponse`](./decorators.md#@TypeSpec.OpenAPI.defaultResponse)
+- [`@extension`](./decorators.md#@TypeSpec.OpenAPI.extension)
+- [`@externalDocs`](./decorators.md#@TypeSpec.OpenAPI.externalDocs)
+- [`@info`](./decorators.md#@TypeSpec.OpenAPI.info)
+- [`@operationId`](./decorators.md#@TypeSpec.OpenAPI.operationId)
 
 ### Models
 
-- [`AdditionalInfo`](./data-types.md#OpenAPI.AdditionalInfo)
-- [`Contact`](./data-types.md#OpenAPI.Contact)
-- [`License`](./data-types.md#OpenAPI.License)
+- [`AdditionalInfo`](./data-types.md#TypeSpec.OpenAPI.AdditionalInfo)
+- [`Contact`](./data-types.md#TypeSpec.OpenAPI.Contact)
+- [`License`](./data-types.md#TypeSpec.OpenAPI.License)
diff --git a/docs/standard-library/openapi3/reference/decorators.md b/docs/standard-library/openapi3/reference/decorators.md
@@ -6,14 +6,14 @@ toc_max_heading_level: 3
 
 # Decorators
 
-## OpenAPI
+## TypeSpec.OpenAPI
 
-### `@oneOf` {#@OpenAPI.oneOf}
+### `@oneOf` {#@TypeSpec.OpenAPI.oneOf}
 
 Specify that `oneOf` should be used instead of `anyOf` for that union.
 
 ```typespec
-@OpenAPI.oneOf
+@TypeSpec.OpenAPI.oneOf
 ```
 
 #### Target
@@ -24,12 +24,12 @@ Specify that `oneOf` should be used instead of `anyOf` for that union.
 
 None
 
-### `@useRef` {#@OpenAPI.useRef}
+### `@useRef` {#@TypeSpec.OpenAPI.useRef}
 
 Specify an external reference that should be used inside of emitting this type.
 
 ```typespec
-@OpenAPI.useRef(ref: valueof string)
+@TypeSpec.OpenAPI.useRef(ref: valueof string)
 ```
 
 #### Target

diff --git a/docs/standard-library/openapi3/reference/index.md b/docs/standard-library/openapi3/reference/index.md
@@ -35,9 +35,9 @@ npm install --save-peer @typespec/openapi3
 
 [See documentation](./emitter.md)
 
-## OpenAPI
+## TypeSpec.OpenAPI
 
 ### Decorators
 
-- [`@oneOf`](./decorators.md#@OpenAPI.oneOf)
-- [`@useRef`](./decorators.md#@OpenAPI.useRef)
+- [`@oneOf`](./decorators.md#@TypeSpec.OpenAPI.oneOf)
+- [`@useRef`](./decorators.md#@TypeSpec.OpenAPI.useRef)
diff --git a/packages/openapi/README.md b/packages/openapi/README.md
@@ -10,7 +10,7 @@ npm install @typespec/openapi
 
 ## Decorators
 
-### OpenAPI
+### TypeSpec.OpenAPI
 
 - [`@defaultResponse`](#@defaultresponse)
 - [`@extension`](#@extension)
@@ -24,7 +24,7 @@ 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.
 
 ```typespec
-@OpenAPI.defaultResponse
+@TypeSpec.OpenAPI.defaultResponse
 ```
 
 ##### Target
@@ -49,7 +49,7 @@ op listPets(): Pet[] | PetStoreResponse;
 Attach some custom data to the OpenAPI element generated from this type.
 
 ```typespec
-@OpenAPI.extension(key: valueof string, value: unknown)
+@TypeSpec.OpenAPI.extension(key: valueof string, value: unknown)
 ```
 
 ##### Target
@@ -81,7 +81,7 @@ op read(): string;
 Specify the OpenAPI `externalDocs` property for this type.
 
 ```typespec
-@OpenAPI.externalDocs(url: valueof string, description?: valueof string)
+@TypeSpec.OpenAPI.externalDocs(url: valueof string, description?: valueof string)
 ```
 
 ##### Target
@@ -111,7 +111,7 @@ Specify OpenAPI additional information.
 The service `title` and `version` are already specified using `@service`.
 
 ```typespec
-@OpenAPI.info(additionalInfo: OpenAPI.AdditionalInfo)
+@TypeSpec.OpenAPI.info(additionalInfo: TypeSpec.OpenAPI.AdditionalInfo)
 ```
 
 ##### Target
@@ -120,16 +120,16 @@ The service `title` and `version` are already specified using `@service`.
 
 ##### Parameters
 
-| Name           | Type                           | Description            |
-| -------------- | ------------------------------ | ---------------------- |
-| additionalInfo | `model OpenAPI.AdditionalInfo` | Additional information |
+| Name           | Type                                    | Description            |
+| -------------- | --------------------------------------- | ---------------------- |
+| additionalInfo | `model TypeSpec.OpenAPI.AdditionalInfo` | Additional information |
 
 #### `@operationId`
 
 Specify the OpenAPI `operationId` property for this operation.
 
 ```typespec
-@OpenAPI.operationId(operationId: valueof string)
+@TypeSpec.OpenAPI.operationId(operationId: valueof string)
 ```
 
 ##### Target

diff --git a/packages/openapi/lib/decorators.tsp b/packages/openapi/lib/decorators.tsp
@@ -1,6 +1,6 @@
 using TypeSpec.Reflection;
 
-namespace OpenAPI;
+namespace TypeSpec.OpenAPI;
 
 /**
  * Specify the OpenAPI `operationId` property for this operation.

diff --git a/packages/openapi/src/decorators.ts b/packages/openapi/src/decorators.ts
@@ -12,7 +12,7 @@ import { setStatusCode } from "@typespec/http";
 import { createStateSymbol, reportDiagnostic } from "./lib.js";
 import { AdditionalInfo, ExtensionKey } from "./types.js";
 
-export const namespace = "OpenAPI";
+export const namespace = "TypeSpec.OpenAPI";
 
 const operationIdsKey = createStateSymbol("operationIds");
 /**

diff --git a/packages/openapi/test/decorators.test.ts b/packages/openapi/test/decorators.test.ts
@@ -169,7 +169,8 @@ describe("openapi: decorators", () => {
 
       expectDiagnostics(diagnostics, {
         code: "invalid-argument",
-        message: "Argument '123' is not assignable to parameter of type 'OpenAPI.AdditionalInfo'",
+        message:
+          "Argument '123' is not assignable to parameter of type 'TypeSpec.OpenAPI.AdditionalInfo'",
       });
     });
 

diff --git a/packages/openapi/test/test-host.ts b/packages/openapi/test/test-host.ts
@@ -10,5 +10,5 @@ export async function createOpenAPITestHost() {
 }
 export async function createOpenAPITestRunner() {
   const host = await createOpenAPITestHost();
-  return createTestWrapper(host, { autoUsings: ["OpenAPI"] });
+  return createTestWrapper(host, { autoUsings: ["TypeSpec.OpenAPI"] });
 }
diff --git a/packages/openapi3/README.md b/packages/openapi3/README.md
@@ -88,7 +88,7 @@ This extension is meant for debugging and should not be depended on.
 
 ## Decorators
 
-### OpenAPI
+### TypeSpec.OpenAPI
 
 - [`@oneOf`](#@oneof)
 - [`@useRef`](#@useref)
@@ -98,7 +98,7 @@ This extension is meant for debugging and should not be depended on.
 Specify that `oneOf` should be used instead of `anyOf` for that union.
 
 ```typespec
-@OpenAPI.oneOf
+@TypeSpec.OpenAPI.oneOf
 ```
 
 ##### Target
@@ -114,7 +114,7 @@ None
 Specify an external reference that should be used inside of emitting this type.
 
 ```typespec
-@OpenAPI.useRef(ref: valueof string)
+@TypeSpec.OpenAPI.useRef(ref: valueof string)
 ```
 
 ##### Target

diff --git a/packages/openapi3/lib/decorators.tsp b/packages/openapi3/lib/decorators.tsp
@@ -1,6 +1,6 @@
 import "../dist/src/index.js";
 
-namespace OpenAPI;
+namespace TypeSpec.OpenAPI;
 
 using TypeSpec.Reflection;
 

diff --git a/packages/openapi3/src/index.ts b/packages/openapi3/src/index.ts
@@ -1,4 +1,4 @@
-export const namespace = "OpenAPI";
+export const namespace = "TypeSpec.OpenAPI";
 
 export * from "./decorators.js";
 export { $lib } from "./lib.js";

diff --git a/packages/openapi3/test/test-host.ts b/packages/openapi3/test/test-host.ts
@@ -36,7 +36,7 @@ export async function createOpenAPITestRunner({
   ${withVersioning ? `import "@typespec/versioning"` : ""};
   using TypeSpec.Rest;
   using TypeSpec.Http;
-  using OpenAPI;
+  using TypeSpec.OpenAPI;
   ${withVersioning ? "using TypeSpec.Versioning;" : ""}
 `;
   return createTestWrapper(host, {
@@ -67,7 +67,7 @@ export async function openApiFor(
     "./main.tsp",
     `import "@typespec/http"; import "@typespec/rest"; import "@typespec/openapi"; import "@typespec/openapi3"; ${
       versions ? `import "@typespec/versioning"; using TypeSpec.Versioning;` : ""
-    }using TypeSpec.Rest;using TypeSpec.Http;using OpenAPI;${code}`
+    }using TypeSpec.Rest;using TypeSpec.Http;using TypeSpec.OpenAPI;${code}`
   );
   const diagnostics = await host.diagnose("./main.tsp", {
     noEmit: false,

diff --git a/packages/openapi3/test/versioning.test.ts b/packages/openapi3/test/versioning.test.ts
@@ -118,7 +118,7 @@ describe("openapi3: versioning", () => {
 
     const runner = createTestWrapper(host, {
       autoImports: [...host.libraries.map((x) => x.name), "./test.js"],
-      autoUsings: ["TypeSpec.Rest", "TypeSpec.Http", "OpenAPI", "TypeSpec.Versioning"],
+      autoUsings: ["TypeSpec.Rest", "TypeSpec.Http", "TypeSpec.OpenAPI", "TypeSpec.Versioning"],
       compilerOptions: { emit: ["@typespec/openapi3"] },
     });
 

diff --git a/packages/playground-website/samples/unions.tsp b/packages/playground-website/samples/unions.tsp
@@ -8,7 +8,7 @@ import "@typespec/openapi3";
 namespace DemoService;
 using TypeSpec.Rest;
 using TypeSpec.Http;
-using OpenAPI;
+using TypeSpec.OpenAPI;
 
 model WidgetBase {
   @key id: string;