diff --git a/docs/site/Server.md b/docs/site/Server.md index 9666c577e7ef..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 @@ -69,40 +74,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 @@ -153,37 +124,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/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 708f305f07cf..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' @@ -305,6 +312,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'