Merge branch 'master' into pr-681

* master: (73 commits) chore: fixes typo in error message for detecting a circular dependency in theme.ts (Redocly#852) chore: minor refactor fix: tidy up non-redoc vendor extension presentation (Redocly#847) chore(cli): redoc-cli v0.8.3 fix(cli): add node-libs-browser to the deps chore(cli): redoc-cli v0.8.2 fix: fix redoc-cli broken dependencies chore: Release 2.0.0-rc.4 🔖 feat: display requestBody description Redocly#833 (Redocly#838) fix: move swagger2openapi to deps because of missing transitive deps chore(cli): redoc-cli v0.8.0 chore: update peerDeps before release chore: Release 2.0.0-rc.3 🔖 fix: add extra deref step for anyOf/oneOf variants chore: Remove duplicate re-export from index.ts (Redocly#842) fix: pin lunr version in ReDoc chore: fix cli declarations feat: support externalValue for examples chore: update deps docs: Fixed docker README, added missing redocly repo name (Redocly#841) ...
mobileposse · Mar 20, 2019 · b311281 · b311281
2 parents ca1f536 + 2f65f05
commit b311281
Show file tree

Hide file tree

Showing 70 changed files with 6,354 additions and 4,031 deletions.
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,12 @@
+*
+!src/
+!config
+!demo/favicon.png
+
+!custom.d.ts
+!typings/styled-patch.d.ts
+!tsconfig.json
+!webpack.config.ts
+
+!package.json
+!yarn.lock
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -27,7 +27,7 @@ You will need [Node.js](http://nodejs.org) at `v8.0.0+` and [Yarn](https://yarnp
 After cloning the repo, run:
 
 ```bash
-$ yarn install # or yarn
+$ yarn install # or npm
 ```
 
 ### Commonly used NPM scripts
@@ -91,4 +91,4 @@ There are some other scripts available in the `scripts` section of the `package.
   - **`src/types`**: contains extra typescript typings including OpenAPI doc typings
   - **`src/utils`**: utility functions
   - **`src/styled-components.ts`**: - reexprots styled-components with proper typescript annotations using theme
-  - **`src/theme.ts`**: - default theme (colors, fonts, etc) used by all the components
+  - **`src/theme.ts`**: - default theme (colors, fonts, etc) used by all the components
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,82 @@
+# [2.0.0-rc.4](https://github.com/Rebilly/ReDoc/compare/v2.0.0-rc.3...v2.0.0-rc.4) (2019-03-15)
+
+
+### Bug Fixes
+
+* move swagger2openapi to deps because of missing transitive deps ([ed9b878](https://github.com/Rebilly/ReDoc/commit/ed9b878))
+
+
+### Features
+
+* display requestBody description [#833](https://github.com/Rebilly/ReDoc/issues/833) ([#838](https://github.com/Rebilly/ReDoc/issues/838)) ([56ca371](https://github.com/Rebilly/ReDoc/commit/56ca371))
+
+
+# [2.0.0-rc.3](https://github.com/Rebilly/ReDoc/compare/v2.0.0-rc.2...v2.0.0-rc.3) (2019-03-15)
+
+
+### Bug Fixes
+
+* add extra deref step for anyOf/oneOf variants ([d81b631](https://github.com/Rebilly/ReDoc/commit/d81b631)), closes [#810](https://github.com/Rebilly/ReDoc/issues/810)
+* duplicate keys in request samples ([3ce5bff](https://github.com/Rebilly/ReDoc/commit/3ce5bff)), closes [#815](https://github.com/Rebilly/ReDoc/issues/815)
+* escape backslashes in string literals ([#823](https://github.com/Rebilly/ReDoc/issues/823)) ([70faca1](https://github.com/Rebilly/ReDoc/commit/70faca1)), closes [#822](https://github.com/Rebilly/ReDoc/issues/822)
+* escape quotes in string values ([0473165](https://github.com/Rebilly/ReDoc/commit/0473165)), closes [#882](https://github.com/Rebilly/ReDoc/issues/882)
+* pin lunr version in ReDoc ([178ff4c](https://github.com/Rebilly/ReDoc/commit/178ff4c)), closes [#844](https://github.com/Rebilly/ReDoc/issues/844)
+* set last section min-height ([4dd79cd](https://github.com/Rebilly/ReDoc/commit/4dd79cd)), closes [#820](https://github.com/Rebilly/ReDoc/issues/820)
+
+
+### Features
+
+* support externalValue for examples ([2cdfcd2](https://github.com/Rebilly/ReDoc/commit/2cdfcd2)), closes [#551](https://github.com/Rebilly/ReDoc/issues/551) [#840](https://github.com/Rebilly/ReDoc/issues/840)
+* **cli:** Add templateOptions param to pass additional data to custom template ([#792](https://github.com/Rebilly/ReDoc/issues/792)) ([4e8ee03](https://github.com/Rebilly/ReDoc/commit/4e8ee03))
+
+
+
+# [2.0.0-rc.2](https://github.com/Rebilly/ReDoc/compare/v2.0.0-rc.1...v2.0.0-rc.2) (2019-01-27)
+
+
+### Bug Fixes
+
+* make padding for md code blocks and code samples consistent ([007752d](https://github.com/Rebilly/ReDoc/commit/007752d))
+* make syntax highlighting for md js code blocks same as for payload samples ([d197c0f](https://github.com/Rebilly/ReDoc/commit/d197c0f))
+* Only display API version if present ([#773](https://github.com/Rebilly/ReDoc/issues/773)) ([fb3cb36](https://github.com/Rebilly/ReDoc/commit/fb3cb36))
+
+
+
+# [2.0.0-rc.1](https://github.com/Rebilly/ReDoc/compare/v2.0.0-rc.0...v2.0.0-rc.1) (2019-01-17)
+
+
+### Bug Fixes
+
+* allow docker container serving under non-root URLs ([#731](https://github.com/Rebilly/ReDoc/issues/731)) ([cfb6f0f](https://github.com/Rebilly/ReDoc/commit/cfb6f0f)), closes [#730](https://github.com/Rebilly/ReDoc/issues/730)
+* make example/defaults badge consistent with code blocks ([fa39ce4](https://github.com/Rebilly/ReDoc/commit/fa39ce4))
+* pattern constrain spacing ([c7436f2](https://github.com/Rebilly/ReDoc/commit/c7436f2))
+* sidebar navigation issues when scrollYOffset is float number ([c04f387](https://github.com/Rebilly/ReDoc/commit/c04f387)), closes [#748](https://github.com/Rebilly/ReDoc/issues/748)
+
+
+
+# [2.0.0-rc.0](https://github.com/Rebilly/ReDoc/compare/v2.0.0-alpha.41...v2.0.0-rc.0) (2018-11-27)
+
+
+### Bug Fixes
+
+* false-positive recursive detection with oneOf ([59eaa8d](https://github.com/Rebilly/ReDoc/commit/59eaa8d)), closes [#723](https://github.com/Rebilly/ReDoc/issues/723) [#585](https://github.com/Rebilly/ReDoc/issues/585)
+* fix hideHostname also hiding basePath ([b5f3224](https://github.com/Rebilly/ReDoc/commit/b5f3224)), closes [#677](https://github.com/Rebilly/ReDoc/issues/677)
+* fix spacing with nested markdown lists ([f2f6909](https://github.com/Rebilly/ReDoc/commit/f2f6909)), closes [#718](https://github.com/Rebilly/ReDoc/issues/718)
+* improve scrolling performance in Chrome with non-wrapped json examples ([a69c402](https://github.com/Rebilly/ReDoc/commit/a69c402))
+* nested oneOf button spacing ([3673720](https://github.com/Rebilly/ReDoc/commit/3673720)), closes [#719](https://github.com/Rebilly/ReDoc/issues/719)
+* onLoaded callback not run on spec error ([e77df0c](https://github.com/Rebilly/ReDoc/commit/e77df0c)), closes [#690](https://github.com/Rebilly/ReDoc/issues/690)
+* theme improvments by [@stasiukanya](https://github.com/stasiukanya) ([e2d0cd5](https://github.com/Rebilly/ReDoc/commit/e2d0cd5))
+* **cli:** old peer dependency issue with styled-components ([#699](https://github.com/Rebilly/ReDoc/issues/699)) ([9e2853c](https://github.com/Rebilly/ReDoc/commit/9e2853c))
+
+
+### Features
+
+* Add feature to specify href for logo explicitly ([#645](https://github.com/Rebilly/ReDoc/issues/645)) ([87fd7d7](https://github.com/Rebilly/ReDoc/commit/87fd7d7))
+* add support for markdown in Server Object ([155d214](https://github.com/Rebilly/ReDoc/commit/155d214))
+* Add support for minLength and maxLength constraint humanization ([#700](https://github.com/Rebilly/ReDoc/issues/700)) ([f40568b](https://github.com/Rebilly/ReDoc/commit/f40568b)), closes [#42](https://github.com/Rebilly/ReDoc/issues/42) [/github.com/Rebilly/ReDoc/issues/42#issuecomment-371883853](https://github.com//github.com/Rebilly/ReDoc/issues/42/issues/issuecomment-371883853)
+
+
+
 <a name="2.0.0-alpha.41"></a>
 # [2.0.0-alpha.41](https://github.com/Rebilly/ReDoc/compare/v2.0.0-alpha.40...v2.0.0-alpha.41) (2018-10-18)
 

diff --git a/README.md b/README.md
@@ -70,6 +70,7 @@ Additionally, all the 1.x releases are hosted on our GitHub Pages-based **CDN**:
 - [Shopify Draft Orders](https://help.shopify.com/api/draft-orders)
 - [Discourse](http://docs.discourse.org)
 - [APIs.guru](https://apis.guru/api-doc/)
+- [FastAPI](https://github.com/tiangolo/fastapi)
 
 ## Deployment
 
@@ -161,7 +162,7 @@ Also you can pass options:
 
 ```js
 <RedocStandalone
-  specUrl="http://rebilly.github.io/RebillyAPI/swagger.json"
+  specUrl="http://rebilly.github.io/RebillyAPI/openapi.json"
   options={{
     nativeScrollbars: true,
     theme: { colors: { main: '#dd5522' } },
@@ -175,7 +176,7 @@ You can also specify `onLoaded` callback which will be called each time Redoc ha
 
 ```js
 <RedocStandalone
-  specUrl="http://rebilly.github.io/RebillyAPI/swagger.json"
+  specUrl="http://rebilly.github.io/RebillyAPI/openapi.json"
   onLoaded={error => {
     if (!error) {
       console.log('Yay!');
@@ -189,11 +190,11 @@ You can also specify `onLoaded` callback which will be called each time Redoc ha
 ReDoc is available as pre-built Docker image in official [Docker Hub repository](https://hub.docker.com/r/redocly/redoc/). You may simply pull & run it:
 
     docker pull redocly/redoc
-    docker run -p 80:8080 redocly/redoc
+    docker run -p 8080:80 redocly/redoc
 
-Also you may rewrite some predefined environment variables defined in [Dockerfile](./Dockerfile). By default ReDoc starts with demo Petstore spec located at `http://petstore.swagger.io/v2/swagger.json`, but you may change this URL using environment variable `SPEC_URL`:
+Also you may rewrite some predefined environment variables defined in [Dockerfile](./config/docker/Dockerfile). By default ReDoc starts with demo Petstore spec located at `http://petstore.swagger.io/v2/swagger.json`, but you may change this URL using environment variable `SPEC_URL`:
 
-    docker run -p 80:8080 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
+    docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc
 
 ## ReDoc CLI
 
@@ -205,7 +206,7 @@ Also you may rewrite some predefined environment variables defined in [Dockerfil
 You can inject Security Definitions widget into any place of your specification `description`. Check out details [here](docs/security-definitions-injection.md).
 
 ### Swagger vendor extensions
-ReDoc makes use of the following [vendor extensions](http://swagger.io/specification/#vendorExtensions):
+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

diff --git a/cli/Dockerfile b/cli/Dockerfile
@@ -0,0 +1,23 @@
+# Package the 'redoc-cli' as a docker image.
+#
+# To build:
+# $ cd <Redoc project directory>
+# $ docker build -t redoc-cli -f cli/Dockerfile .
+#
+# To run:
+# To display the command line options:
+# $ docker run --rm -it redoc-cli --help
+# .. will display the comand line help
+#
+# To turn `swagger.yml` file in the current directory, to html documentation 'redoc-static.html'
+# $  docker run --rm -it  -v $PWD:/data redoc-cli bundle swagger.yml
+
+FROM node:alpine
+
+RUN npm install -g redoc-cli
+
+WORKDIR /data
+EXPOSE 8080
+
+ENTRYPOINT ["redoc-cli"]
+CMD []
diff --git a/cli/README.md b/cli/README.md
@@ -17,5 +17,6 @@ Some examples:
 - Bundle with main color changed to `orange`: <br> `$ redoc-cli bundle [spec] --options.theme.colors.primary.main=orange`
 - Serve with `nativeScrollbars` option set to true: <br> `$ redoc-cli serve [spec] --options.nativeScrollbars`
 - Bundle using custom template (check [default template](https://github.com/Rebilly/ReDoc/blob/master/cli/template.hbs) for reference): <br> `$ redoc-cli bundle [spec] -t custom.hbs`
+- Bundle using custom template and add custom `templateOptions`: <br> `$ redoc-cli bundle [spec] -t custom.hbs --templateOptions.metaDescription "Page meta description"`
 
 For more details run `redoc-cli --help`.
diff --git a/cli/index.ts b/cli/index.ts
@@ -6,14 +6,15 @@ import { ServerStyleSheet } from 'styled-components';
 
 import { compile } from 'handlebars';
 import { createServer, IncomingMessage, ServerResponse } from 'http';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 
 import * as zlib from 'zlib';
 
 // @ts-ignore
 import { createStore, loadAndBundleSpec, Redoc } from 'redoc';
 
-import { createReadStream, existsSync, readFileSync, ReadStream, watch, writeFileSync } from 'fs';
+import { watch } from 'chokidar';
+import { createReadStream, existsSync, readFileSync, ReadStream, writeFileSync } from 'fs';
 import * as mkdirp from 'mkdirp';
 
 import * as YargsParser from 'yargs';
@@ -24,7 +25,9 @@ interface Options {
   cdn?: boolean;
   output?: string;
   title?: string;
+  port?: number;
   templateFileName?: string;
+  templateOptions?: any;
   redocOptions?: any;
 }
 
@@ -60,15 +63,16 @@ YargsParser.command(
     return yargs;
   },
   async argv => {
-    const config = {
-      ssr: argv.ssr,
-      watch: argv.watch,
-      templateFileName: argv.template,
+    const config: Options = {
+      ssr: argv.ssr as boolean,
+      watch: argv.watch as boolean,
+      templateFileName: argv.template as string,
+      templateOptions: argv.templateOptions || {},
       redocOptions: argv.options || {},
     };
 
     try {
-      await serve(argv.port, argv.spec, config);
+      await serve(argv.port as number, argv.spec as string, config);
     } catch (e) {
       handleError(e);
     }
@@ -105,12 +109,13 @@ YargsParser.command(
       return yargs;
     },
     async argv => {
-      const config = {
+      const config: Options = {
         ssr: true,
-        output: argv.o,
-        cdn: argv.cdn,
-        title: argv.title,
-        templateFileName: argv.template,
+        output: argv.o as string,
+        cdn: argv.cdn as boolean,
+        title: argv.title as string,
+        templateFileName: argv.template as string,
+        templateOptions: argv.templateOptions || {},
         redocOptions: argv.options || {},
       };
 
@@ -127,6 +132,10 @@ YargsParser.command(
     describe: 'Path to handlebars page template, see https://git.io/vh8fP for the example ',
     type: 'string',
   })
+  .options('templateOptions', {
+    describe:
+      'Additional options that you want pass to template. Use dot notation, e.g. templateOptions.metaDescription',
+  })
   .options('options', {
     describe: 'ReDoc options, use dot notation, e.g. options.nativeScrollbars',
   }).argv;
@@ -167,28 +176,26 @@ async function serve(port: number, pathToSpec: string, options: Options = {}) {
   server.listen(port, () => console.log(`Server started: http://127.0.0.1:${port}`));
 
   if (options.watch && existsSync(pathToSpec)) {
-    const pathToSpecDirectory = dirname(pathToSpec);
+    const pathToSpecDirectory = resolve(dirname(pathToSpec));
     const watchOptions = {
-      recursive: true,
+      ignored: /(^|[\/\\])\../,
     };
 
-    watch(
-      pathToSpecDirectory,
-      watchOptions,
-      debounce(async (event, filename) => {
-        if (event === 'change' || event === 'rename') {
-          console.log(`${join(pathToSpecDirectory, filename)} changed, updating docs`);
-          try {
-            spec = await loadAndBundleSpec(pathToSpec);
-            pageHTML = await getPageHTML(spec, pathToSpec, options);
-            console.log('Updated successfully');
-          } catch (e) {
-            console.error('Error while updating: ', e.message);
-          }
+    const watcher = watch(pathToSpecDirectory, watchOptions);
+    const log = console.log.bind(console);
+    watcher
+      .on('change', async path => {
+        log(`${path} changed, updating docs`);
+        try {
+          spec = await loadAndBundleSpec(pathToSpec);
+          pageHTML = await getPageHTML(spec, pathToSpec, options);
+          log('Updated successfully');
+        } catch (e) {
+          console.error('Error while updating: ', e.message);
         }
-      }, 2200),
-    );
-    console.log(`👀  Watching ${pathToSpecDirectory} for changes...`);
+      })
+      .on('error', error => console.error(`Watcher error: ${error}`))
+      .on('ready', () => log(`👀  Watching ${pathToSpecDirectory} for changes...`));
   }
 }
 
@@ -209,7 +216,7 @@ async function bundle(pathToSpec, options: Options = {}) {
 async function getPageHTML(
   spec: any,
   pathToSpec: string,
-  { ssr, cdn, title, templateFileName, redocOptions = {} }: Options,
+  { ssr, cdn, title, templateFileName, templateOptions, redocOptions = {} }: Options,
 ) {
   let html;
   let css;
@@ -252,6 +259,7 @@ async function getPageHTML(
           : `<script>${redocStandaloneSrc}</script>`) + css
       : '<script src="redoc.standalone.js"></script>',
     title,
+    templateOptions,
   });
 }
 
@@ -291,17 +299,6 @@ function respondWithGzip(
   }
 }
 
-function debounce(callback: (...args) => void, time: number) {
-  let interval;
-  return (...args) => {
-    clearTimeout(interval);
-    interval = setTimeout(() => {
-      interval = null;
-      callback(...args);
-    }, time);
-  };
-}
-
 function isURL(str: string): boolean {
   return /^(https?:)\/\//m.test(str);
 }

diff --git a/cli/package.json b/cli/package.json
@@ -1,23 +1,25 @@
 {
   "name": "redoc-cli",
-  "version": "0.6.4",
+  "version": "0.8.3",
   "description": "ReDoc's Command Line Interface",
   "main": "index.js",
   "bin": "index.js",
   "repository": "https://github.com/Rebilly/ReDoc",
   "author": "Roman Hotsiy <gotsijroman@gmail.com>",
   "license": "MIT",
   "dependencies": {
+    "chokidar": "^2.0.4",
     "handlebars": "^4.0.11",
     "isarray": "^2.0.4",
     "mkdirp": "^0.5.1",
     "mobx": "^4.2.0",
-    "react": "^16.4.2",
-    "react-dom": "^16.4.2",
-    "redoc": "^2.0.0-alpha.37",
-    "styled-components": "^3.4.0",
+    "node-libs-browser": "^2.2.0",
+    "react": "^16.8.4",
+    "react-dom": "^16.8.4",
+    "redoc": "^2.0.0-rc.4",
+    "styled-components": "^4.1.3",
     "tslib": "^1.9.3",
-    "yargs": "^12.0.1"
+    "yargs": "^12.0.5"
   },
   "scripts": {
     "ci-publish": "ci-publish"
@@ -26,6 +28,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/chokidar": "^1.7.5",
     "@types/handlebars": "^4.0.39",
     "@types/mkdirp": "^0.5.2",
     "ci-publish": "^1.3.1"