fix: depreacate x-code-samples, rename to x-codeSamples for consistency

Redocly · May 10, 2020 · becc2f5 · becc2f5
1 parent 6e607b9
commit becc2f5
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -211,7 +211,7 @@ You can inject Security Definitions widget into any place of your specification
 ReDoc makes use of the following [vendor extensions](https://swagger.io/specification/#specificationExtensions):
 * [`x-logo`](docs/redoc-vendor-extensions.md#x-logo) - is used to specify API logo
 * [`x-traitTag`](docs/redoc-vendor-extensions.md#x-traitTag) - useful for handling out common things like Pagination, Rate-Limits, etc
-* [`x-code-samples`](docs/redoc-vendor-extensions.md#x-code-samples) - specify operation code samples
+* [`x-codeSamples`](docs/redoc-vendor-extensions.md#x-codeSamples) - specify operation code samples
 * [`x-examples`](docs/redoc-vendor-extensions.md#x-examples) - specify JSON example for requests
 * [`x-nullable`](docs/redoc-vendor-extensions.md#x-nullable) - mark schema param as a nullable
 * [`x-displayName`](docs/redoc-vendor-extensions.md#x-displayname) - specify human-friendly names for the menu categories

diff --git a/demo/openapi.yaml b/demo/openapi.yaml
@@ -114,7 +114,7 @@ paths:
         - petstore_auth:
             - 'write:pets'
             - 'read:pets'
-      x-code-samples:
+      x-codeSamples:
         - lang: 'C#'
           source: |
             PetStore.v1.Pet pet = new PetStore.v1.Pet();
@@ -162,7 +162,7 @@ paths:
         - petstore_auth:
             - 'write:pets'
             - 'read:pets'
-      x-code-samples:
+      x-codeSamples:
         - lang: PHP
           source: |
             $form = new \PetStore\Entities\Pet();
@@ -587,7 +587,7 @@ paths:
                   description: Response for cancelling subscription
                 '500':
                   description: Callback processing failed and retries will be performed
-              x-code-samples:
+              x-codeSamples:
                 - lang: 'C#'
                   source: |
                     PetStore.v1.Pet pet = new PetStore.v1.Pet();

diff --git a/docs/redoc-vendor-extensions.md b/docs/redoc-vendor-extensions.md
@@ -162,13 +162,13 @@ x-traitTag: true
 
 ### Operation Object vendor extensions
 Extends OpenAPI [Operation Object](http://swagger.io/specification/#operationObject)
-#### x-code-samples
+#### x-codeSamples
 | Field Name     |	Type	  | Description |
 | :------------- | :------: | :---------- |
-| x-code-samples | [ [Code Sample Object](#codeSampleObject) ]  | A list of code samples associated with operation |
+| x-codeSamples | [ [Code Sample Object](#codeSampleObject) ]  | A list of code samples associated with operation |
 
 ###### Usage in ReDoc
-`x-code-samples` are rendered on the right panel of ReDoc
+`x-codeSamples` are rendered on the right panel of ReDoc
 
 #### <a name="codeSampleObject"></a>Code Sample Object
 Operation code sample

diff --git a/src/services/models/Operation.ts b/src/services/models/Operation.ts
@@ -39,6 +39,8 @@ export function isPayloadSample(
   return sample.lang === 'payload' && (sample as any).requestBodyContent;
 }
 
+let isCodeSamplesWarningPrinted = false;
+
 /**
  * Operation model ready to be used by components
  */
@@ -173,7 +175,12 @@ export class OperationModel implements IMenuItem {
   @memoize
   get codeSamples() {
     let samples: Array<OpenAPIXCodeSample | XPayloadSample> =
-      this.operationSpec['x-code-samples'] || [];
+      this.operationSpec['x-codeSamples'] || this.operationSpec['x-code-samples'] || [];
+
+    if (this.operationSpec['x-code-samples'] && !isCodeSamplesWarningPrinted) {
+      isCodeSamplesWarningPrinted = true;
+      console.warn('"x-code-samples" is deprecated. Use "x-codeSamples" instead');
+    }
 
     const requestBodyContent = this.requestBody && this.requestBody.content;
     if (requestBodyContent && requestBodyContent.hasSample) {

diff --git a/src/types/open-api.d.ts b/src/types/open-api.d.ts
@@ -76,7 +76,8 @@ export interface OpenAPIOperation {
   deprecated?: boolean;
   security?: OpenAPISecurityRequirement[];
   servers?: OpenAPIServer[];
-  'x-code-samples'?: OpenAPIXCodeSample[];
+  'x-codeSamples'?: OpenAPIXCodeSample[];
+  'x-code-samples'?: OpenAPIXCodeSample[]; // deprecated
 }
 
 export interface OpenAPIParameter {

diff --git a/src/utils/openapi.ts b/src/utils/openapi.ts
@@ -569,7 +569,8 @@ export const shortenHTTPVerb = verb =>
 export function isRedocExtension(key: string): boolean {
   const redocExtensions = {
     'x-circular-ref': true,
-    'x-code-samples': true,
+    'x-code-samples': true, // deprecated
+    'x-codeSamples': true,
     'x-displayName': true,
     'x-examples': true,
     'x-ignoredHeaderParameters': true,