Internal Express Swagger

Thin wrapper around https://www.npmjs.com/package/swagger-ui-express, adding access restriction to team members using Google Oauth. It also adds an easy way to declare route documentation in Javascript.

Installation

1npm install --save @layer0/internal-express-swagger

Configuration

Google Oauth

You will need Google Oauth credentials to authenticate your users with. Those credentials need to allow the callback URI redirecting to your API.

The callback URI is constructed as:

https://<your-host>/<API docs mount path>/auth/callback

For example if your API is hosted at https://my.api, and the docs are mounted on /api-docs, the allowed redirect uri must be https://my.api/api-docs/auth/callback.

Note that this is optional, pass googleOauthConfig: null to skip the restriction

Cookie secret

Generate a long string (~256 chars) and keep it secret.

This ensures that the authorization cookie was produced by the API and not been forged.

If your already have cookie-parser mounted on your Express App, you can ignore this parameter

Allowed domains

Provide a list of email domains that are allowed to access the API docs. Other gmail accounts will be rejected.

Development

1. Copy .env.dist into .env and setup your Google credentials and allowed domains.
2. Run npm start and open http://localhost:3000/api-docs

Usage

1const express = require('express');
2const app = express();
3const port = 3000;
4const InternalExpressSwagger = require('@layer0/internal-express-swagger');
5
6const apiDoc = new InternalExpressSwagger({
7  // See Swagger 2.0 specifications https://swagger.io/specification/v2/#info-object for 'info' field
8  info: {
9    title: 'Pet Store',
10    description: 'API for my Pet Store'
11  },
12  googleOauthConfig: {
13    cookieSecret: process.env.COOKIE_SECRET,
14    googleClientId: process.env.GOOGLE_CLIENT_ID,
15    googleClientSecret: process.env.GOOGLE_CLIENT_SECRET,
16    allowedDomains: process.env.ALLOWED_DOMAINS.split(','),
17  },
18});
19
20// See Swagger 2.0 specifications https://swagger.io/specification/v2/#paths-object for the 'path' field
21apiDoc.get('/pet/{id}', {
22  description: 'Retrieve a pet by ID',
23  parameters: [
24    {
25      name: 'id',
26      in: 'path',
27      type: 'string',
28      description: 'ID of your pet',
29      required: true,
30      example: '1',
31    },
32  ],
33  produces: ['application/json'],
34  responses: {
35    200: {
36      examples: {
37        'application/json': {
38          id: 1,
39          name: 'Medor',
40        },
41      },
42    },
43  },
44});
45
46app.use('/api-docs', apiDoc.serve());
47
48app.listen(port, () => {
49  console.log(`Example app listening at http://localhost:${port}`);
50});

Check out the server example for more details