From f8925facf822f9bdb1cb2d3d14aea644d4e2840f Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sun, 12 Sep 2021 21:41:29 -0400 Subject: [PATCH 01/14] Updates readme with about section and organizes features list --- README.md | 93 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 77 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 855dac49..9ed57fa8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@
ReDoc logo - **OpenAPI/Swagger-generated API Reference Documentation** + # Generate interactive API documentation from OpenAPI definitions [![Build Status](https://travis-ci.com/Redocly/redoc.svg?branch=master)](https://travis-ci.com/Redocly/redoc) [![Coverage Status](https://coveralls.io/repos/Redocly/redoc/badge.svg?branch=master&service=github)](https://coveralls.io/github/Redocly/redoc?branch=master) [![dependencies Status](https://david-dm.org/Redocly/redoc/status.svg)](https://david-dm.org/Redocly/redoc) [![devDependencies Status](https://david-dm.org/Redocly/redoc/dev-status.svg)](https://david-dm.org/Redocly/redoc#info=devDependencies) [![npm](http://img.shields.io/npm/v/redoc.svg)](https://www.npmjs.com/package/redoc) [![License](https://img.shields.io/npm/l/redoc.svg)](https://github.com/Redocly/redoc/blob/master/LICENSE) @@ -11,30 +11,60 @@ **This is the README for the `2.x` version of Redoc (React-based).** **The README for the `1.x` version is on the [v1.x](https://github.com/Redocly/redoc/tree/v1.x) branch** +## About Redoc + +Redoc is an open-source tool for generating OpenAPI(aka Swagger) definitions. By default +Redoc offers a three-panel, responsive layout: the left panel contains a search bar and navigation menu, +the central panel contains the documentation, and the right panel contains request and response +examples. + ![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) -## [Live demo](http://redocly.github.io/redoc/) +## Live demo -[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) [ReDoc as a service](https://redoc.ly) [Customization services](https://redoc.ly/#services) +If you want to see how ReDoc will render your OpenAPI definition, +you can try it out online at https://redocly.github.io/redoc/. + +A version of the Swagger Petstore API is displayed by default. +To test it with your own OpenAPI definition, +enter the URL for your definition and select **TRY IT**. + +## Redoc vs. Redocly Reference docs + +Redoc Community Edition is free open-source software (OSS). +Redocly has developed extensive enhancements on top of Redoc Community Edition's open core, creating Redocly Reference Docs. +See [Comparison Redoc CE vs. Redocly Reference Docs](https://redoc.ly/redoc-vs-reference/) +for the main differences between the Redoc Community Edition and Redocly Reference Docs. + +## Deploy to GitHub +[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) + +## Redoc as a service +[Redoc as a service](https://redoc.ly/workflows) ## Features -- [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/) -- [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands) -- [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/) - - [See an example](https://github.com/APIs-guru/create-react-app-redoc) -- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redoc.ly/docs/redoc/quickstart/cli/) - Responsive three-panel design with menu/scrolling synchronization +- [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/) - Deep linking support +- [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands) - Ability to integrate your API introduction into the side menu -- High-level grouping in side-menu with [`x-tagGroups`](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension +- [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/) + + [Example repo](https://github.com/APIs-guru/create-react-app-redoc) +- [Command-line interface to bundle your docs into a **zero-dependency** HTML file](https://redoc.ly/docs/redoc/quickstart/cli/) +- Neat **interactive** documentation for nested objects
+ ![](docs/images/nested-demo.gif) + +## Customization options +[Customization services](https://redoc.ly/#services) +- High-level grouping in side-menu with the [`x-tagGroups`](https://redoc.ly/docs/api-reference-docs/specification-extensions/x-tag-groups/) specification extension - Branding/customizations using the [`theme` option](https://redoc.ly/docs/api-reference-docs/configuration/theming/) + +## Support - OpenAPI v3.0 support - Basic OpenAPI v3.1 support - Broad OpenAPI v2.0 feature support (yes, it supports even `discriminator`)
![](docs/images/discriminator-demo.gif) -- Neat **interactive** documentation for nested objects
- ![](docs/images/nested-demo.gif) - Code samples support (via vendor extension)
![](docs/images/code-samples-demo.gif) @@ -44,7 +74,7 @@ - `next` release: https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(deprecated)**: -- particular release, e.g. `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js +- particular release, for example `v1.2.0`: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js - `v1.x.x` release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js - `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. @@ -67,15 +97,46 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - [BoxKnight](https://www.docs.boxknight.com/) ## Deployment + +### TL;DR final code example + +```html + + + + Redoc + + + + + + + + + + + + + + +``` + For step-by-step instructions for how to get started using Redoc to render your OpenAPI definition, refer to the -[Redoc quickstart guide](https://redoc.ly/docs/redoc/quickstart/intro/). +[**Redoc quickstart guide**](https://redoc.ly/docs/redoc/quickstart/intro/). -[**IE11 Support Notes**](docs/usage-with-ie11.md) +See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on ## ReDoc CLI For more information on Redoc's commmand-line interface, refer to -[Using the Redoc CLI](https://redoc.ly/docs/redoc/quickstart/cli/). +[**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/). ## Configuration From 899d7f9637815619d708ef8cfd1078b6339bfe61 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Mon, 13 Sep 2021 07:22:18 -0400 Subject: [PATCH 02/14] Adds some notes to deployment --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 9ed57fa8..5647e2fd 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,9 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d ### TL;DR final code example +To render your OpenAPI definition using Redoc, use the following HTML code sample and +replace the `spec-url` attribute with the url or local file address to your definition. + ```html @@ -133,6 +136,7 @@ to render your OpenAPI definition, refer to the [**Redoc quickstart guide**](https://redoc.ly/docs/redoc/quickstart/intro/). See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on +IE support for Redoc. ## ReDoc CLI For more information on Redoc's commmand-line interface, refer to From c87600d520f037d291169b44b5803a35af16b5a5 Mon Sep 17 00:00:00 2001 From: Ivana Isadora Devcic <33730345+skadinna@users.noreply.github.com> Date: Tue, 21 Sep 2021 22:17:48 +0200 Subject: [PATCH 03/14] fix: Redoc spelling --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5647e2fd..7205e4f7 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ examples. ## Live demo -If you want to see how ReDoc will render your OpenAPI definition, +If you want to see how Redoc will render your OpenAPI definition, you can try it out online at https://redocly.github.io/redoc/. A version of the Swagger Petstore API is displayed by default. @@ -138,7 +138,7 @@ to render your OpenAPI definition, refer to the See [**IE11 Support Notes**](docs/usage-with-ie11.md) for information on IE support for Redoc. -## ReDoc CLI +## Redoc CLI For more information on Redoc's commmand-line interface, refer to [**Using the Redoc CLI**](https://redoc.ly/docs/redoc/quickstart/cli/). From 669adddc9dc3590df997b234e274b849c708d715 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Wed, 22 Sep 2021 22:17:19 -0400 Subject: [PATCH 04/14] Updates per reviews and adds new logo --- README.md | 13 ++++++++----- docs/images/redoc.png | Bin 0 -> 8047 bytes 2 files changed, 8 insertions(+), 5 deletions(-) create mode 100644 docs/images/redoc.png diff --git a/README.md b/README.md index 5647e2fd..7f55d8af 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- ReDoc logo + ReDoc logo # Generate interactive API documentation from OpenAPI definitions @@ -13,10 +13,13 @@ ## About Redoc -Redoc is an open-source tool for generating OpenAPI(aka Swagger) definitions. By default -Redoc offers a three-panel, responsive layout: the left panel contains a search bar and navigation menu, -the central panel contains the documentation, and the right panel contains request and response -examples. +Redoc is an open-source tool for generating documentation from OpenAPI (fka Swagger) definitions. + +By default Redoc offers a three-panel, responsive layout: + +- The left panel contains a search bar and navigation menu. +- The central panel contains the documentation. +- The right panel contains request and response examples. ![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) diff --git a/docs/images/redoc.png b/docs/images/redoc.png new file mode 100644 index 0000000000000000000000000000000000000000..15579760928b664b526cc89aedceecfb72460154 GIT binary patch literal 8047 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 Date: Wed, 22 Sep 2021 22:20:49 -0400 Subject: [PATCH 05/14] Minor edits --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 93de7281..cc80f831 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ By default Redoc offers a three-panel, responsive layout: - The central panel contains the documentation. - The right panel contains request and response examples. -![ReDoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) +![Redoc demo](https://raw.githubusercontent.com/Redocly/redoc/master/demo/redoc-demo.png) ## Live demo @@ -82,7 +82,7 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - `latest` release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - it will point to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg. ## Version Guidance -| ReDoc Release | OpenAPI Specification | +| Redoc Release | OpenAPI Specification | |:--------------|:----------------------| | 2.0.0-alpha.54| 3.1, 3.0.x, 2.0 | | 2.0.0-alpha.x | 3.0, 2.0 | From 1c8578ea8840b9e0cc8f66eda317c6839b9c1383 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:40:39 -0400 Subject: [PATCH 06/14] Adds comparison table and OpenAPI link section --- README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index cc80f831..5074978b 100644 --- a/README.md +++ b/README.md @@ -32,23 +32,53 @@ A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your definition and select **TRY IT**. -## Redoc vs. Redocly Reference docs +## Redoc vs. Reference vs. Portals -Redoc Community Edition is free open-source software (OSS). -Redocly has developed extensive enhancements on top of Redoc Community Edition's open core, creating Redocly Reference Docs. -See [Comparison Redoc CE vs. Redocly Reference Docs](https://redoc.ly/redoc-vs-reference/) -for the main differences between the Redoc Community Edition and Redocly Reference Docs. +Redoc is Redocly's community-edition product. Looking for something more? +Checkout the following feature comparison of Redocly's premium products versus Redoc: -## Deploy to GitHub -[Deploy to Github](https://github.com/Rebilly/generator-openapi-repo#generator-openapi-repo--) +| Features | Redoc | Reference | Portals | +|------------------------------|:---------:|:---------:|:-----------:| +| **Specs** | | | | +| Swagger 2.0 | √ | √ | √ | +| OpenAPI 3.0 | √ | √ | √ | +| OpenAPI 3.1 | √ (basic) | √ | √ | +| | | | | +| **Theming** | | | | +| Fonts/colors | √ | √ | √ | +| Extra theme options | | √ | √ | +| | | | | +| **Performance** | | | | +| Pagination | | √ | √ | +| Search (enhanced) | | √ | √ | +| Search (server-side) | | | √ | +| | | | | +| **Multiple APIs** | | | | +| Multiple versions | | √ | √ | +| Multiple APIs | | | √ | +| API catalog | | | √ | +| | | | | +| **Additional features** | | | | +| Try-it console | | √ | √ | +| Automated code samples | | √ | √ | +| Deep links | | √ | √ | +| More SEO control | | | √ | +| Contextual docs | | | √ | +| Landing pages | | | √ | +| React hooks for more control | | | √ | +| Personalization | | | √ | +| Analytics integrations | | | √ | +| Feedback | | | Coming Soon | -## Redoc as a service -[Redoc as a service](https://redoc.ly/workflows) +Refer to the Redocly's documentation for more information on these products: + +- [Portals](https://redoc.ly/docs/developer-portal/introduction/) +- [Reference](https://redoc.ly/docs/api-reference-docs/getting-started/) +- [Redoc](https://redoc.ly/docs/redoc/quickstart/intro/) ## Features - Responsive three-panel design with menu/scrolling synchronization - [Multiple deployment options](https://redoc.ly/docs/redoc/quickstart/intro/) -- Deep linking support - [Server-side rendering (SSR) ready](https://redoc.ly/docs/redoc/quickstart/cli/#redoc-cli-commands) - Ability to integrate your API introduction into the side menu - [Simple integration with `create-react-app`](https://redoc.ly/docs/redoc/quickstart/react/) @@ -99,6 +129,14 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN **(d - [APIs.guru](https://apis.guru/api-doc/) - [BoxKnight](https://www.docs.boxknight.com/) +## Lint OpenAPI definitions + +Redocly's OpenAPI CLI is an open source command-line tool that you can use to lint +your OpenAPI definition. Linting helps you to catch errors and inconsistencies in your +OpenAPI definition before publishing. + +Refer to [Lint configuration](https://redoc.ly/docs/cli/guides/lint/) in the OpenAPI documentation for more information. + ## Deployment ### TL;DR final code example From 3cc6ea458973f7d8bb95e43687808c4743ebce39 Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:44:37 -0400 Subject: [PATCH 07/14] Minor edit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5074978b..82f09b27 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- ReDoc logo + Redoc logo # Generate interactive API documentation from OpenAPI definitions From c4564de324d78c86e4436cf7ee0aa5b8c63f48ca Mon Sep 17 00:00:00 2001 From: Heather Cloward Date: Sat, 9 Oct 2021 14:46:36 -0400 Subject: [PATCH 08/14] Updates image src --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 82f09b27..3aad1e42 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- Redoc logo + Redoc logo # Generate interactive API documentation from OpenAPI definitions From 35f77878de7d1dd250040771f17757a5a6ce85f9 Mon Sep 17 00:00:00 2001 From: Roman Marshevskyy Date: Mon, 11 Oct 2021 10:53:28 +0300 Subject: [PATCH 09/14] fix: OpenAPI 3.1: Missing description when $ref used #1727 --- src/services/OpenAPIParser.ts | 12 ++++++ src/services/__tests__/OpenAPIParser.test.ts | 14 +++++++ .../__snapshots__/OpenAPIParser.test.ts.snap | 7 ++++ .../fixtures/siblingRefDescription.json | 39 +++++++++++++++++++ src/services/models/Schema.ts | 2 +- 5 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 src/services/__tests__/fixtures/siblingRefDescription.json diff --git a/src/services/OpenAPIParser.ts b/src/services/OpenAPIParser.ts index 11a001aa..1683e927 100644 --- a/src/services/OpenAPIParser.ts +++ b/src/services/OpenAPIParser.ts @@ -174,6 +174,18 @@ export class OpenAPIParser { return obj; } + shallowDeref(obj: OpenAPIRef | T): T { + if (this.isRef(obj)) { + const schemaName = getDefinitionName(obj.$ref); + if (schemaName && this.options.ignoreNamedSchemas.has(schemaName)) { + return { type: 'object', title: schemaName } as T; + } + const resolved = this.byRef(obj.$ref); + return this.allowMergeRefs ? this.mergeRefs(obj, resolved, false) : (resolved as T); + } + return obj; + } + mergeRefs(ref, resolved, mergeAsAllOf: boolean) { // eslint-disable-next-line @typescript-eslint/no-unused-vars const { $ref, ...rest } = ref; diff --git a/src/services/__tests__/OpenAPIParser.test.ts b/src/services/__tests__/OpenAPIParser.test.ts index b79f61b4..b8b211ba 100644 --- a/src/services/__tests__/OpenAPIParser.test.ts +++ b/src/services/__tests__/OpenAPIParser.test.ts @@ -1,5 +1,6 @@ import { OpenAPIParser } from '../OpenAPIParser'; import { RedocNormalizedOptions } from '../RedocNormalizedOptions'; +import { OpenAPIParameter, Referenced } from '../../types'; const opts = new RedocNormalizedOptions({}); @@ -13,5 +14,18 @@ describe('Models', () => { parser = new OpenAPIParser(spec, undefined, opts); expect(parser.mergeAllOf(spec.components.schemas.test)).toMatchSnapshot(); }); + + test('should override description from $ref of the referenced component, when sibling description exists ', () => { + // eslint-disable-next-line @typescript-eslint/no-var-requires + const spec = require('./fixtures/siblingRefDescription.json'); + parser = new OpenAPIParser(spec, undefined, opts); + const schemaOrRef: Referenced = { + $ref: '#/components/schemas/Test', + description: 'Overriden description', + }; + + expect(parser.shallowDeref(schemaOrRef)).toMatchSnapshot(); + }); + }); }); diff --git a/src/services/__tests__/__snapshots__/OpenAPIParser.test.ts.snap b/src/services/__tests__/__snapshots__/OpenAPIParser.test.ts.snap index 74a26ed0..ffbcbff5 100644 --- a/src/services/__tests__/__snapshots__/OpenAPIParser.test.ts.snap +++ b/src/services/__tests__/__snapshots__/OpenAPIParser.test.ts.snap @@ -86,3 +86,10 @@ Object { ], } `; + +exports[`Models Schema should override description from $ref of the referenced component, when sibling description exists 1`] = ` +Object { + "description": "Overriden description", + "type": "object", +} +`; diff --git a/src/services/__tests__/fixtures/siblingRefDescription.json b/src/services/__tests__/fixtures/siblingRefDescription.json new file mode 100644 index 00000000..b090a963 --- /dev/null +++ b/src/services/__tests__/fixtures/siblingRefDescription.json @@ -0,0 +1,39 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "AA", + "version": "1.0" + }, + "paths": { + "/test": { + "get": { + "operationId": "test", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "testAttr": { + "description": "Overriden description", + "$ref": "#/components/schemas/Test" + } + } + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Test": { + "type": "object", + "description": "Refed description" + } + } + } +} diff --git a/src/services/models/Schema.ts b/src/services/models/Schema.ts index d79d738b..1b23cf5f 100644 --- a/src/services/models/Schema.ts +++ b/src/services/models/Schema.ts @@ -78,7 +78,7 @@ export class SchemaModel { makeObservable(this); this.pointer = schemaOrRef.$ref || pointer || ''; - this.rawSchema = parser.deref(schemaOrRef, false, true); + this.rawSchema = parser.shallowDeref(schemaOrRef); this.schema = parser.mergeAllOf(this.rawSchema, this.pointer, isChild); this.init(parser, isChild); From fe6909ed80dd6053b48c30f63a2460614bf957a9 Mon Sep 17 00:00:00 2001 From: Roman Marshevskyy Date: Mon, 11 Oct 2021 11:51:17 +0300 Subject: [PATCH 10/14] fix: OpenAPI 3.1: Missing description when $ref used #1727 --- src/services/OpenAPIParser.ts | 7 ------- src/services/models/MediaType.ts | 2 +- src/utils/openapi.ts | 4 ++-- 3 files changed, 3 insertions(+), 10 deletions(-) diff --git a/src/services/OpenAPIParser.ts b/src/services/OpenAPIParser.ts index 1683e927..399ce1d5 100644 --- a/src/services/OpenAPIParser.ts +++ b/src/services/OpenAPIParser.ts @@ -206,13 +206,6 @@ export class OpenAPIParser { } } - shalowDeref(obj: OpenAPIRef | T): T { - if (this.isRef(obj)) { - return this.byRef(obj.$ref)!; - } - return obj; - } - /** * Merge allOf constraints. * @param schema schema with allOF diff --git a/src/services/models/MediaType.ts b/src/services/models/MediaType.ts index 9e41d89a..25dae807 100644 --- a/src/services/models/MediaType.ts +++ b/src/services/models/MediaType.ts @@ -40,7 +40,7 @@ export class MediaTypeModel { this.examples = { default: new ExampleModel( parser, - { value: parser.shalowDeref(info.example) }, + { value: parser.shallowDeref(info.example) }, name, info.encoding, ), diff --git a/src/utils/openapi.ts b/src/utils/openapi.ts index ad267722..d0b081f5 100644 --- a/src/utils/openapi.ts +++ b/src/utils/openapi.ts @@ -505,13 +505,13 @@ export function mergeParams( ): Array> { const operationParamNames = {}; operationParams.forEach(param => { - param = parser.shalowDeref(param); + param = parser.shallowDeref(param); operationParamNames[param.name + '_' + param.in] = true; }); // filter out path params overridden by operation ones with the same name pathParams = pathParams.filter(param => { - param = parser.shalowDeref(param); + param = parser.shallowDeref(param); return !operationParamNames[param.name + '_' + param.in]; }); From 952c05c6b4b95fe6082611fed9e2f0913272b904 Mon Sep 17 00:00:00 2001 From: AlexVarchuk Date: Mon, 11 Oct 2021 12:40:56 +0300 Subject: [PATCH 11/14] fix: improve publish action scripts (#1729) --- .github/workflows/demo-deploy-s3.yml | 42 ---------- .github/workflows/e2e-tests.yml | 12 +++ .github/workflows/publish-cli.yml | 115 +++++++++++++++++++++++++++ .github/workflows/publish.yml | 100 +++++++++++++++++++++++ .github/workflows/unit-tests.yml | 2 +- .travis.yml | 32 -------- 6 files changed, 228 insertions(+), 75 deletions(-) delete mode 100644 .github/workflows/demo-deploy-s3.yml create mode 100644 .github/workflows/e2e-tests.yml create mode 100644 .github/workflows/publish-cli.yml create mode 100644 .github/workflows/publish.yml delete mode 100644 .travis.yml diff --git a/.github/workflows/demo-deploy-s3.yml b/.github/workflows/demo-deploy-s3.yml deleted file mode 100644 index efb2ca19..00000000 --- a/.github/workflows/demo-deploy-s3.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: Redoc demo CI/CD - -on: - push: - tags: - - v[0-9]*.[0-9]*.[0-9]* - -jobs: - build-and-unit: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - run: npm ci - - run: npm run bundle - - run: npm test - deploy: - needs: build-and-unit - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v1 - - name: cache node modules - uses: actions/cache@v1 - with: - path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS - key: npm-${{ hashFiles('package-lock.json') }} - restore-keys: | - npm-${{ hashFiles('package-lock.json') }} - npm- - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v1 - with: - aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} - aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - aws-region: us-east-1 - - name: Install dependencies - run: npm ci - - name: Build package - run: npm run build:demo - - name: Deploy to S3 bucket - run: npm run deploy:demo - - name: Invalidate - run: aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DEMO_DISTRIBUTION_ID }} --paths "/*" diff --git a/.github/workflows/e2e-tests.yml b/.github/workflows/e2e-tests.yml new file mode 100644 index 00000000..514a3193 --- /dev/null +++ b/.github/workflows/e2e-tests.yml @@ -0,0 +1,12 @@ +name: Tests e2e + +on: [push] + +jobs: + build-and-e2e: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - run: npm ci + - run: npm run bundle + - run: npm run e2e diff --git a/.github/workflows/publish-cli.yml b/.github/workflows/publish-cli.yml new file mode 100644 index 00000000..9bfa3fff --- /dev/null +++ b/.github/workflows/publish-cli.yml @@ -0,0 +1,115 @@ +name: Publish cli + +on: + push: + tags: + - v[0-9]*.[0-9]*.[0-9]* + + +jobs: + bundle: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + - name: Cache node modules + uses: actions/cache@v2 + with: + path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: | + npm-${{ hashFiles('package-lock.json') }} + npm- + - run: npm ci + - run: npm run bundle + - name: Store bundle artifact + uses: actions/upload-artifact@v2 + with: + name: bundles-cli + path: bundles + retention-days: 1 + unit-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - run: npm ci + - run: npm test + e2e-tests: + needs: [bundle] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - run: npm ci + - name: Download bundled artifact + uses: actions/download-artifact@v2 + with: + name: bundles + path: bundles-cli + - run: npm run e2e + bundle-cli: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + - name: Cache node modules + uses: actions/cache@v2 + with: + path: ~/.npm + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: | + npm-${{ hashFiles('package-lock.json') }} + npm- + - name: Install dependencies + run: npm ci + - name: Bundle + run: npm run compile:cli + - name: Store bundle artifact + uses: actions/upload-artifact@v2 + with: + name: cli + path: cli + retention-days: 1 + check-version-cli: + name: Check Version + runs-on: ubuntu-latest + needs: [bundle-cli, unit-tests, e2e-tests] + outputs: + changed: ${{ steps.check.outputs.changed }} + steps: + - name: Checkout repository + uses: actions/checkout@v2 + - name: Set up Node.js + uses: actions/setup-node@v2 + - name: Check if version has been updated + id: check + uses: EndBug/version-check@v2.0.1 + with: + file-name: ./cli/package.json + file-url: https://unpkg.com/redoc-cli/package.json + static-checking: localIsNew + publish-cli: + needs: [ check-version-cli ] + if: needs.check-version-cli.outputs.changed == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/setup-node@v1 + with: + node-version: "14.x" + - uses: actions/checkout@v2 + - name: Download cli bundled artifact + uses: actions/download-artifact@v2 + with: + name: cli + path: cli + - name: Cache node modules + uses: actions/cache@v2 + with: + path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: | + npm-${{ hashFiles('package-lock.json') }} + npm- + - name: Publish to NPM + run: cd cli/ && npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..d1c9ccbf --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,100 @@ +name: Publish + +on: + push: + tags: + - v[0-9]*.[0-9]*.[0-9]* + +jobs: + bundle: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v2 + - name: Cache node modules + uses: actions/cache@v2 + with: + path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: | + npm-${{ hashFiles('package-lock.json') }} + npm- + - run: npm ci + - run: npm run bundle + - name: Store bundle artifact + uses: actions/upload-artifact@v2 + with: + name: bundles + path: bundles + retention-days: 1 + unit-tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - run: npm ci + - run: npm test + e2e-tests: + needs: [bundle] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - run: npm ci + - name: Download bundled artifact + uses: actions/download-artifact@v2 + with: + name: bundles + path: bundles + - run: npm run e2e + deploy-demo: + needs: [bundle, unit-tests, e2e-tests] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - name: Configure AWS Credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + aws-region: us-east-1 + - name: Install dependencies + run: npm ci + - name: Download bundled artifacts + uses: actions/download-artifact@v2 + with: + name: bundles + path: bundles + - name: Build package + run: npm run build:demo + - name: Deploy to S3 bucket + run: npm run deploy:demo + - name: Invalidate + run: aws cloudfront create-invalidation --distribution-id ${{ secrets.CF_DEMO_DISTRIBUTION_ID }} --paths "/*" + publish: + needs: [bundle, unit-tests, e2e-tests] + runs-on: ubuntu-latest + steps: + - uses: actions/setup-node@v1 + with: + node-version: "14.x" + - uses: actions/checkout@v2 + - name: Download bundled artifacts + uses: actions/download-artifact@v2 + with: + name: bundles + path: bundles + - name: Cache node modules + uses: actions/cache@v2 + with: + path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: | + npm-${{ hashFiles('package-lock.json') }} + npm- + - name: Before deploy + run: npm run declarations + - name: Publish to NPM + run: npm publish + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: After script + run: cat ./coverage/lcov.info | coveralls diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index 09e54a63..a0a0bbd1 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -9,4 +9,4 @@ jobs: - uses: actions/checkout@v1 - run: npm ci - run: npm run bundle - - run: npm test + - run: npm test \ No newline at end of file diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 03ac1fa4..00000000 --- a/.travis.yml +++ /dev/null @@ -1,32 +0,0 @@ -language: node_js -node_js: -- '12' -cache: - directories: - - "~/.cache" -env: - global: - - GH_REF: github.com/Redocly/redoc.git - - GIT_AUTHOR_EMAIL: redoc-bot@users.noreply.github.com - - GIT_AUTHOR_NAME: RedocBot - - secure: apiavCfCQngL9Een1m7MIXMf3bqO3rY4YY59TMBl/yFKi80CEsHPHhgVUkl6hC+aM5PeBt/vgjh37rHMX31j/pcSZ4Z8SO/4Bwr36iHfhSxSEuAQog8P07qWqH7wYYWGIVmF682stgl0fYF+GN92sx/6edFVzsWVECf2G7imtICKSTbhKGm3Dhn2JwGnhD7eyfgZ33omgiaswumdu0xABoXDfqSZR+16fC4Ap5rhv3fXO9ndvRNy1STn376nT+my6e86UrQL4aS/S+HNHgIe1BUs+5cOp6Jgw6t0ie7phY0EAiECsRxy9K4e3Dctv9m6+Wma4+vy65MS0zGyrqey6oyV4l827sCOjrD1qcqc9bX6FlMSouVoNfE4ZjINNAbgigTaiLSoDSPcf5I5smkkM2ezzFOMSZwZxNdaNL2LKb97vc8m/ZUkv0sKZyT7oqVL7aJweEivsSHj5l2KR8Z7XrVB1y2eI6GvyTSa/d+CL4dSRzjh8+IRN047YBrdTKD5IkdT0upfoBu14WPUfFmLKxX+iMCslXRWb6kwojhrWNYmZvL65KRAzJ6+eIPDG/W5QUOpYyYT77bLlBQjVo6NmVvl9v3HMECq9CHH0ivKFBGPiKMOx7cJkTax3FuyznOW2WCXB9kTb5Zk9toaiNlSp9L6ll/h2Eyxa6n6sWUgmmM= - - secure: vVRg9BKGBwF2MbXQnEccFL+XW0/7RaBmge9k7jbGYScBwkP3XjnQ/Xaj0cvTz2CM2EqXsbpwfvr4Jo+enW/E3MGy5RiEzv5hUe/jIFRR0gfAFbZxSTvg5xiFhTDffqQk0fncO4jXu+wPO5lZ2CMRWzyXz3i1MZhjMcAgoDr1+TRss/EGXLNHxr2RM88tpUW0fV2prIRoyGqhCgnYZtrm7hmr41Ej+itg1MqZLml/Rjkt3KsNgI+z0O5Qn3QSAO8GtPZqeftQxAjevOmxZGcssxY8EJvqbjAujr4y51WncXpEmCRPSY2J9R5+fkgZurqwnJapbQpjwKYemok3ps7EHg2gWkAlmPdQO4LKpbffGkM/o5b+8+HdIuQZugsSWQD9hUSftTAFLcfA1isi7V2lHE1m8bX/vk9zIyDdcPSwIaFe9y+w3PexwFmTjPLq+nia/UY2kARFZMEIFAJby6gkA70DcAJ50QOM86InJu5DSzGbIssgTGAXCn0TPPyGveaurVLw8x61j3yh8LDF46gUHey3rqv6WjpCM9h/vg7X/gq5ve/5Q2KHscUKfs/sA53Mt7qPeqRZY1QCaaRjzqJO/ZraHqWWeKmPKaWhPGR0kYEnkvB+K9GZ+HNSWCltjCO4SJ1xeEl7CRqQxAwdiMATF5SKqyiC+bn5oc35mFgbRF8= - - secure: ela1tn4wkJQZ8O4iv+4pIZi5cebxeCStVF1tEUe6qa6WWgJYVXmS2tEv3QQ36NUBFrP58Y6yl10XguPnvj/2BCqcZI4FUBHh3BfiBoUtXxDCVKI5LtlniNiOFGUwfzEeYka8T51zFlcUXSCCaxHkRZbmBsIzeJ39UwTi5fy0qwLv9GgL0czhwm8I8sZ8gyWdGmqpXNFEsb9JP4ZA3mw2qpWkGpGAqQPD9XSCkU3LmX1/ltwsBMAgGYKLLo7vU8d5KV2c8L1Gnxfl6BvfmqUD/dsas/1rnk08rU2nez5ekuQa2tJRkDLOv8bqvrGRLjHSUa3yPuisC6SsDGSU7/3DcozZyYsz7WQ6WI8tYabyjqqeJTF1N8a5T3IbZaZNV1J4JHOO9Cb/y7gIg4edANg6tbe7MzZpdEPRBnw6OkdTdirpNsWQ/jnfpY1hn6mraQZz/q8yaz3W21NjbBJhVnvfh5gWLKQ3YAAziCBhmmrThFhUu0czz+G920MuFo477TBcxvlrE7CaNJ0Q6yYkDehEPOv3jvEs1QVHPwuRrlaLTbBhrlTICKZ58gdX30O8N4i0Xgp/v6qrC03bplnMQc8E/uC61wcVLJixnlZVp8FODpUvPjsxVFkpuNSOIAaiqcERmoiPXx05Epzmr78hjU5rYCx/1MmVoeB4gs9YO+4guD4= -addons: - chrome: stable - apt: - packages: - - libgconf-2-4 -before_script: npm run bundle -script: npm test && ([ "${TRAVIS_PULL_REQUEST}" = "false" ] && npm run e2e-ci || npm - run e2e) -after_script: cat ./coverage/lcov.info | coveralls -before_deploy: npm run compile:cli && npm run declarations -deploy: -- provider: npm - skip_cleanup: true - email: gotsijroman@gmail.com - tag: next - api_key: "$NPM_TOKEN" - on: - tags: true From 43451ba4cd24270b8629a967d3fd2ce2eed8912e Mon Sep 17 00:00:00 2001 From: kylenarocroc <3884351+kylenarocroc@users.noreply.github.com> Date: Mon, 11 Oct 2021 10:50:09 +0100 Subject: [PATCH 12/14] feat: add q/kdb+ syntax highlighting (#1605) --- src/utils/highlight.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/utils/highlight.ts b/src/utils/highlight.ts index 036b9129..23cdd43d 100644 --- a/src/utils/highlight.ts +++ b/src/utils/highlight.ts @@ -15,6 +15,7 @@ import 'prismjs/components/prism-objectivec.js'; import 'prismjs/components/prism-perl.js'; import 'prismjs/components/prism-php.js'; import 'prismjs/components/prism-python.js'; +import 'prismjs/components/prism-q.js'; import 'prismjs/components/prism-ruby.js'; import 'prismjs/components/prism-scala.js'; import 'prismjs/components/prism-sql.js'; From 3b8d6441bd9978b849a53021d40fd4fe150272ea Mon Sep 17 00:00:00 2001 From: Andriy Zaleskyy Date: Mon, 11 Oct 2021 13:05:50 +0300 Subject: [PATCH 13/14] fix: The number of items in the array in the array is incorrect #1762 (#1763) --- demo/openapi-3-1.yaml | 14 ++++++++++++ demo/openapi.yaml | 2 ++ src/components/Schema/ArraySchema.tsx | 13 +++++------ .../DiscriminatorDropdown.test.tsx.snap | 4 ++++ src/services/models/Schema.ts | 4 ++++ .../loadAndBundleSpec.test.ts.snap | 22 +++++++++++++++++++ src/utils/__tests__/openapi.test.ts | 8 +++---- 7 files changed, 55 insertions(+), 12 deletions(-) diff --git a/demo/openapi-3-1.yaml b/demo/openapi-3-1.yaml index 31063d4b..ac89619d 100644 --- a/demo/openapi-3-1.yaml +++ b/demo/openapi-3-1.yaml @@ -533,6 +533,20 @@ paths: subscriptionId: type: string example: AAA-123-BBB-456 + '200': + description: Successful operation + content: + application/json: + schema: + type: array + maxItems: 999 + minItems: 0 + items: + type: array + maxItems: 777 + minItems: 111 + items: + type: number callbacks: orderInProgress: '{$request.body#/callbackUrl}?event={$request.body#/eventName}': diff --git a/demo/openapi.yaml b/demo/openapi.yaml index c570cc60..5cf19340 100644 --- a/demo/openapi.yaml +++ b/demo/openapi.yaml @@ -377,7 +377,9 @@ paths: application/xml: schema: type: array + maxItems: 999 items: + maxItems: 111 $ref: '#/components/schemas/Pet' '400': description: Invalid tag value diff --git a/src/components/Schema/ArraySchema.tsx b/src/components/Schema/ArraySchema.tsx index eab37595..0b555c07 100644 --- a/src/components/Schema/ArraySchema.tsx +++ b/src/components/Schema/ArraySchema.tsx @@ -13,15 +13,12 @@ const PaddedSchema = styled.div` export class ArraySchema extends React.PureComponent { render() { - const itemsSchema = this.props.schema.items!; const schema = this.props.schema; + const itemsSchema = schema.items; - const itemConstraintSchema = ( - min: number | undefined = undefined, - max: number | undefined = undefined, - ) => ({ type: 'array', minItems: min, maxItems: max }); - - const minMaxItems = humanizeConstraints(itemConstraintSchema(itemsSchema?.schema?.minItems, itemsSchema?.schema?.maxItems)); + const minMaxItems = schema.minItems === undefined && schema.maxItems === undefined ? + '' : + `(${humanizeConstraints(schema)})`; if (schema.displayType && !itemsSchema && !minMaxItems.length) { return (
@@ -31,7 +28,7 @@ export class ArraySchema extends React.PureComponent { return (
- Array ({minMaxItems}) + Array {minMaxItems} diff --git a/src/components/__tests__/__snapshots__/DiscriminatorDropdown.test.tsx.snap b/src/components/__tests__/__snapshots__/DiscriminatorDropdown.test.tsx.snap index fe5617ed..7af7b482 100644 --- a/src/components/__tests__/__snapshots__/DiscriminatorDropdown.test.tsx.snap +++ b/src/components/__tests__/__snapshots__/DiscriminatorDropdown.test.tsx.snap @@ -33,6 +33,8 @@ exports[`Components SchemaView discriminator should correctly render discriminat "format": undefined, "isCircular": undefined, "isPrimitive": true, + "maxItems": undefined, + "minItems": undefined, "options": "<<>>", "pattern": undefined, "pointer": "#/components/schemas/Dog/properties/packSize", @@ -86,6 +88,8 @@ exports[`Components SchemaView discriminator should correctly render discriminat "format": undefined, "isCircular": undefined, "isPrimitive": true, + "maxItems": undefined, + "minItems": undefined, "options": "<<>>", "pattern": undefined, "pointer": "#/components/schemas/Dog/properties/type", diff --git a/src/services/models/Schema.ts b/src/services/models/Schema.ts index 1b23cf5f..81dc7ee3 100644 --- a/src/services/models/Schema.ts +++ b/src/services/models/Schema.ts @@ -63,6 +63,8 @@ export class SchemaModel { const: any; contentEncoding?: string; contentMediaType?: string; + minItems?: number; + maxItems?: number; /** * @param isChild if schema discriminator Child @@ -128,6 +130,8 @@ export class SchemaModel { this.const = schema.const || ''; this.contentEncoding = schema.contentEncoding; this.contentMediaType = schema.contentMediaType; + this.minItems = schema.minItems; + this.maxItems = schema.maxItems; if (!!schema.nullable || schema['x-nullable']) { if (Array.isArray(this.type) && !this.type.some((value) => value === null || value === 'null')) { diff --git a/src/utils/__tests__/__snapshots__/loadAndBundleSpec.test.ts.snap b/src/utils/__tests__/__snapshots__/loadAndBundleSpec.test.ts.snap index 7807e39e..6cd0a034 100644 --- a/src/utils/__tests__/__snapshots__/loadAndBundleSpec.test.ts.snap +++ b/src/utils/__tests__/__snapshots__/loadAndBundleSpec.test.ts.snap @@ -729,7 +729,9 @@ try { "schema": Object { "items": Object { "$ref": "#/components/schemas/Pet", + "maxItems": 111, }, + "maxItems": 999, "type": "array", }, }, @@ -3245,6 +3247,26 @@ culpa qui officia deserunt mollit anim id est laborum. }, }, "responses": Object { + "200": Object { + "content": Object { + "application/json": Object { + "schema": Object { + "items": Object { + "items": Object { + "type": "number", + }, + "maxItems": 777, + "minItems": 111, + "type": "array", + }, + "maxItems": 999, + "minItems": 0, + "type": "array", + }, + }, + }, + "description": "Successful operation", + }, "201": Object { "content": Object { "application/json": Object { diff --git a/src/utils/__tests__/openapi.test.ts b/src/utils/__tests__/openapi.test.ts index d4f23e02..6f40d974 100644 --- a/src/utils/__tests__/openapi.test.ts +++ b/src/utils/__tests__/openapi.test.ts @@ -412,10 +412,10 @@ describe('Utils', () => { describe('openapi humanizeConstraints', () => { const itemConstraintSchema = ( - min: number | undefined = undefined, - max: number | undefined = undefined, - multipleOf: number | undefined = undefined, - uniqueItems?: boolean, + min?: number, + max?: number, + multipleOf?: number, + uniqueItems?: boolean ) => ({ type: 'array', minItems: min, maxItems: max, multipleOf, uniqueItems }); it('should not have a humanized constraint without schema constraints', () => { From 4fb9c835256b9e44bcecabde7baf0f0f3e5beb3f Mon Sep 17 00:00:00 2001 From: Roman Hotsiy Date: Mon, 11 Oct 2021 15:02:08 +0300 Subject: [PATCH 14/14] fix: fix deref logic for oas3.1 (#1767) --- src/services/OpenAPIParser.ts | 2 +- src/services/models/Schema.ts | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/services/OpenAPIParser.ts b/src/services/OpenAPIParser.ts index 399ce1d5..4881c99e 100644 --- a/src/services/OpenAPIParser.ts +++ b/src/services/OpenAPIParser.ts @@ -195,7 +195,7 @@ export class OpenAPIParser { } if (mergeAsAllOf && keys.some((k) => k !== 'description' && k !== 'title' && k !== 'externalDocs')) { return { - allOf: [resolved, rest], + allOf: [rest, resolved], }; } else { // small optimization diff --git a/src/services/models/Schema.ts b/src/services/models/Schema.ts index 81dc7ee3..b155d254 100644 --- a/src/services/models/Schema.ts +++ b/src/services/models/Schema.ts @@ -80,7 +80,7 @@ export class SchemaModel { makeObservable(this); this.pointer = schemaOrRef.$ref || pointer || ''; - this.rawSchema = parser.shallowDeref(schemaOrRef); + this.rawSchema = parser.deref(schemaOrRef, false, true); this.schema = parser.mergeAllOf(this.rawSchema, this.pointer, isChild); this.init(parser, isChild); @@ -363,7 +363,7 @@ function buildFields( ): FieldModel[] { const props = schema.properties || {}; const additionalProps = schema.additionalProperties; - const defaults = schema.default || {}; + const defaults = schema.default; let fields = Object.keys(props || []).map((fieldName) => { let field = props[fieldName]; @@ -384,7 +384,7 @@ function buildFields( required, schema: { ...field, - default: field.default === undefined ? defaults[fieldName] : field.default, + default: field.default === undefined && defaults ? defaults[fieldName] : field.default, }, }, $ref + '/properties/' + fieldName,