docs: deprecate operation.getExtension(), typing improvements (#852)

* chore: deprecate operation.getExtension * chore: various type improvements
readmeio · Apr 8, 2024 · 882be39 · 882be39
1 parent 9a630a4
commit 882be39
Show file tree

Hide file tree

Showing 3 changed files with 5 additions and 3 deletions.
diff --git a/packages/oas-normalize/src/index.ts b/packages/oas-normalize/src/index.ts
@@ -205,7 +205,7 @@ export default class OASNormalize {
    * Retrieve OpenAPI, Swagger, or Postman version information about the supplied API definition.
    *
    */
-  version() {
+  async version(): Promise<{ specification: 'openapi' | 'postman' | 'swagger'; version: string | 'unknown' }> {
     return this.load().then(schema => {
       switch (utils.getAPIDefinitionType(schema)) {
         case 'openapi':

diff --git a/packages/oas/README.md b/packages/oas/README.md
@@ -230,7 +230,6 @@ const operation = petstore.operation('/pet', 'post');
 <!-- prettier-ignore-start -->
 | Method | Description |
 | :--- | :--- |
-| `#getExtension()` | Retrieve a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) if it exists on this operation. |
 | `#hasExtension()` | Determine if a given [specification extension](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions) exists on this operation. |
 <!-- prettier-ignore-end -->
 

diff --git a/packages/oas/src/operation/index.ts b/packages/oas/src/operation/index.ts
@@ -2,6 +2,7 @@ import type { CallbackExamples } from './lib/get-callback-examples.js';
 import type { getParametersAsJSONSchemaOptions } from './lib/get-parameters-as-json-schema.js';
 import type { RequestBodyExamples } from './lib/get-requestbody-examples.js';
 import type { ResponseExamples } from './lib/get-response-examples.js';
+import type { Extensions } from '../extensions.js';
 import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 
 import findSchemaDefinition from '../lib/find-schema-definition.js';
@@ -785,8 +786,10 @@ export class Operation {
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions}
    * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#specificationExtensions}
    * @param extension Specification extension to lookup.
+   *
+   * @deprecated Use `oas.getExtension(extension, operation)` instead.
    */
-  getExtension(extension: string) {
+  getExtension(extension: string | keyof Extensions) {
     return this.schema?.[extension];
   }
 }