From 806db8212fce86efb607330a3e881512bbd0cd02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Thu, 18 Jun 2020 10:22:52 +0200 Subject: [PATCH 1/3] docs: extract "Enabling HTTPS" into a deployment guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Hage Yaapa Signed-off-by: Miroslav Bajtoš --- docs/site/Server.md | 31 --------- docs/site/guides/deployment/enabling-https.md | 67 +++++++++++++++++++ docs/site/sidebars/lb4_sidebar.yml | 4 ++ 3 files changed, 71 insertions(+), 31 deletions(-) create mode 100644 docs/site/guides/deployment/enabling-https.md diff --git a/docs/site/Server.md b/docs/site/Server.md index 9666c577e7ef..42cae87a952b 100644 --- a/docs/site/Server.md +++ b/docs/site/Server.md @@ -153,37 +153,6 @@ Explorer UI. Please refer to [Self-hosted REST API Explorer](./Self-hosted-REST-API-Explorer.md) for more details. -### Enable HTTPS - -Enabling HTTPS for the LoopBack REST server is just a matter of specifying the -protocol as `https` and specifying the credentials. - -In the following app, we configure HTTPS for a bare minimum app using a key + -certificate chain variant. - -```ts -import {RestApplication, RestServer, RestBindings} from '@loopback/rest'; -import fs from 'fs'; - -export async function main() { - const options = { - rest: { - protocol: 'https', - key: fs.readFileSync('./key.pem'), - cert: fs.readFileSync('./cert.pem'), - }, - }; - const app = new RestApplication(options); - app.handler(handler => { - handler.response.send('Hello'); - }); - await app.start(); - - const url = app.restServer.url; - console.log(`Server is running at ${url}`); -} -``` - ### Customize CORS [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) is enabled diff --git a/docs/site/guides/deployment/enabling-https.md b/docs/site/guides/deployment/enabling-https.md new file mode 100644 index 000000000000..154ba769ee48 --- /dev/null +++ b/docs/site/guides/deployment/enabling-https.md @@ -0,0 +1,67 @@ +--- +lang: en +title: 'Enabling HTTPS' +keywords: LoopBack 4.0, LoopBack 4, Node.js, HTTPS, Deployment +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Enabling-https.html +--- + +Enabling HTTPS for the LoopBack REST server is just a matter of updating the +`rest` section of application configuration: + +1. Specify the protocol as `https`. +2. Provide TLS server credentials. + +Example: + +```ts +const config = { + rest: { + protocol: 'https', + key: fs.readFileSync('./key.pem'), + cert: fs.readFileSync('./cert.pem'), + // port, host, etc. + }, +}; +``` + +See +[Node.js documentation](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener) +for supported forms of HTTPS/TLS credentials, in particular +[`tls.createSecureContext()` options](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options). + +In the following app, we configure HTTPS for a bare minimum app using a key + +certificate chain variant. + +{% include code-caption.html content="/src/index.ts" %} + +```ts +import {ApplicationConfig, TodoListApplication} from './application'; + +export async function main(options: ApplicationConfig = {}) { + // left out for brevity +} + +if (require.main === module) { + // Run the application + const config = { + rest: { + port: +(process.env.PORT ?? 3000), + host: process.env.HOST ?? 'localhost', + openApiSpec: { + // useful when used with OpenAPI-to-GraphQL to locate your application + setServersFromRequest: true, + }, + + // Enable HTTPS + protocol: 'https', + key: fs.readFileSync('./key.pem'), + cert: fs.readFileSync('./cert.pem'), + }, + }; + main(config).catch(err => { + console.error('Cannot start the application.', err); + process.exit(1); + }); +} +``` diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml index 708f305f07cf..589cd36bbd27 100644 --- a/docs/site/sidebars/lb4_sidebar.yml +++ b/docs/site/sidebars/lb4_sidebar.yml @@ -305,6 +305,10 @@ children: url: Deployment.html output: 'web, pdf' children: + - title: 'Enabling HTTPS' + url: 'Enabling-https.html' + output: 'web, pdf' + - title: 'Deploying to IBM Cloud' url: Deploying-to-IBM-Cloud.html output: 'web, pdf' From b5c5946c6f06033d7b4c57112d5f01dcad0e7d36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Thu, 18 Jun 2020 11:25:42 +0200 Subject: [PATCH 2/3] docs: extract "How to customize OpenAPI serving" into a guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Hage Yaapa Signed-off-by: Miroslav Bajtoš --- docs/site/Server.md | 34 --------------- docs/site/guides/rest/customize-openapi.md | 48 ++++++++++++++++++++++ docs/site/sidebars/lb4_sidebar.yml | 7 ++++ 3 files changed, 55 insertions(+), 34 deletions(-) create mode 100644 docs/site/guides/rest/customize-openapi.md diff --git a/docs/site/Server.md b/docs/site/Server.md index 42cae87a952b..07c0dd486f8a 100644 --- a/docs/site/Server.md +++ b/docs/site/Server.md @@ -69,40 +69,6 @@ const app = new RestApplication({ }); ``` -### Customize How OpenAPI Spec is Served - -There are a few options under `rest.openApiSpec` to configure how OpenAPI spec -is served by the given REST server. - -- servers: Configure servers for OpenAPI spec -- setServersFromRequest: Set `servers` based on HTTP request headers, default to - `false` -- disabled: Set to `true` to disable endpoints for the OpenAPI spec. It will - disable API Explorer too. -- endpointMapping: Maps urls for various forms of the spec. Default to: - -```js - { - '/openapi.json': {version: '3.0.0', format: 'json'}, - '/openapi.yaml': {version: '3.0.0', format: 'yaml'}, - } -``` - -```ts -const app = new RestApplication({ - rest: { - openApiSpec: { - servers: [{url: 'http://127.0.0.1:8080'}], - setServersFromRequest: false, - endpointMapping: { - '/openapi.json': {version: '3.0.0', format: 'json'}, - '/openapi.yaml': {version: '3.0.0', format: 'yaml'}, - }, - }, - }, -}); -``` - ### Configure the API Explorer LoopBack allows externally hosted API Explorer UI to render the OpenAPI diff --git a/docs/site/guides/rest/customize-openapi.md b/docs/site/guides/rest/customize-openapi.md new file mode 100644 index 000000000000..4303762259e4 --- /dev/null +++ b/docs/site/guides/rest/customize-openapi.md @@ -0,0 +1,48 @@ +--- +lang: en +title: 'Customizing how OpenAPI spec is served' +keywords: LoopBack 4.0, LoopBack 4, Node.js, OpenAPI, Customization +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Customizing-how-openapi-spec-is-served.html +--- + +By default, LoopBack REST API server provides endpoints exposing an OpenAPI spec +document describing application's API. You can configure this behavior using +`rest.openApiSpec` field in the configuration object passed to `RestApplication` +constructor. + +- servers: Configure servers for OpenAPI spec + +- setServersFromRequest: Set `servers` based on HTTP request headers, default to + `false` + +- disabled: Set to `true` to disable endpoints for the OpenAPI spec. It will + disable API Explorer too. + +- endpointMapping: Maps urls for various forms of the spec. Default to: + + ```js + { + '/openapi.json': {version: '3.0.0', format: 'json'}, + '/openapi.yaml': {version: '3.0.0', format: 'yaml'}, + } + ``` + +Example application configuration object showing possible customizations: + +{% include code-caption.html content="/src/index.ts" %} + +```ts +const config: ApplicationConfig = { + rest: { + openApiSpec: { + servers: [{url: 'http://127.0.0.1:8080'}], + setServersFromRequest: false, + endpointMapping: { + '/openapi.json': {version: '3.0.0', format: 'json'}, + '/openapi.yaml': {version: '3.0.0', format: 'yaml'}, + }, + }, + }; +}); +``` diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml index 589cd36bbd27..37bfaa29c7aa 100644 --- a/docs/site/sidebars/lb4_sidebar.yml +++ b/docs/site/sidebars/lb4_sidebar.yml @@ -181,6 +181,13 @@ children: output: 'web, pdf' children: + - title: 'Building REST APIs' + output: 'web, pdf' + children: + - title: 'Customizing how OpenAPI spec is served' + url: Customizing-how-openapi-spec-is-served.html + output: 'web, pdf' + - title: 'Create Other Forms of APIs' url: Create-other-forms-of-apis.html output: 'web, pdf' From ceff7ab0c8ab8fcfe30ac25a6a167d867094e7a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Bajto=C5=A1?= Date: Tue, 23 Jun 2020 09:40:15 +0200 Subject: [PATCH 3/3] docs: add "Common tasks" to "Server.md" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a section with links to How-to guides related to Servers, to make it easier to find the content we are extracting from Servers page to elsewhere. Signed-off-by: Miroslav Bajtoš --- docs/site/Server.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/site/Server.md b/docs/site/Server.md index 07c0dd486f8a..199ba6329504 100644 --- a/docs/site/Server.md +++ b/docs/site/Server.md @@ -17,6 +17,11 @@ for requests on a specific port, handle them, and return appropriate responses. A single application can have multiple server instances listening on different ports and working with different protocols. +## Common tasks + +- [Enable HTTPS](./guides/deployment/enabling-https.md) +- [Customize how OpenAPI spec is served](./guides/rest/customize-openapi.md) + ## Usage LoopBack 4 offers the