feat: Add ability to expose Swagger specification (#1577)

docker-compose-dev.yml

@@ -51,6 +51,9 @@ services:
       # will be sent through this proxy if set.
       # - OUTGOING_PROXY=http://proxy:3128
 
+      # Set to true to expose the Swagger specification at /swagger.json
+      # - SWAGGER_EXPOSED=false
+
       # - S3_ENDPOINT=
       # - S3_REGION=
       # - S3_ACCESS_KEY_ID=

docker-compose.yml

@@ -65,6 +65,9 @@ services:
       # which you can control via OUTGOING_BLOCKED_* and OUTGOING_ALLOWED_* below.
       # - OUTGOING_PROXY=http://proxy:3128
 
+      # Set to true to expose the Swagger specification at /swagger.json
+      # - SWAGGER_EXPOSED=false
+
       # - S3_ENDPOINT=
       # - S3_REGION=
       # - S3_ACCESS_KEY_ID=

server/.env.sample

@@ -42,6 +42,9 @@ SECRET_KEY=notsecretkey
 # will be sent through this proxy if set.
 # OUTGOING_PROXY=http://proxy:3128
 
+# Set to true to expose the Swagger specification at /swagger.json
+# SWAGGER_EXPOSED=false
+
 # S3_ENDPOINT=
 # S3_REGION=
 # S3_ACCESS_KEY_ID=

server/api/controllers/swagger/show.js

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) 2024 PLANKA Software GmbH
+ * Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SWAGGER_PATH = path.join(sails.config.appPath, 'swagger.json');
+
+module.exports = {
+  async fn() {
+    if (!sails.config.custom.swaggerExposed) {
+      return this.res.notFound();
+    }
+
+    let specification;
+    try {
+      const content = fs.readFileSync(SWAGGER_PATH, 'utf8');
+      specification = JSON.parse(content);
+    } catch (error) {
+      sails.log.warn('swagger.json not found, run "npm run swagger:generate" to create it');
+      return this.res.notFound();
+    }
+
+    return specification;
+  },
+};

server/build.js

@@ -2,6 +2,10 @@ const fs = require('fs');
 const path = require('path');
 // eslint-disable-next-line import/no-extraneous-dependencies
 const ignore = require('ignore');
+// eslint-disable-next-line import/no-extraneous-dependencies
+const swaggerJsdoc = require('swagger-jsdoc');
+
+const swaggerConfig = require('./config/swagger');
 
 const OUT_DIR = 'dist';
 
@@ -37,6 +41,9 @@ const build = (src, dest) => {
       fs.copyFileSync(srcPath, destPath);
     }
   }
+
+  const specification = swaggerJsdoc(swaggerConfig);
+  fs.writeFileSync(path.join(dest, 'swagger.json'), JSON.stringify(specification, null, 2));
 };
 
 build('./', OUT_DIR);

server/config/custom.js

@@ -64,6 +64,7 @@ module.exports.custom = {
 
   showDetailedAuthErrors: process.env.SHOW_DETAILED_AUTH_ERRORS === 'true',
   outgoingProxy: process.env.OUTGOING_PROXY,
+  swaggerExposed: process.env.SWAGGER_EXPOSED === 'true',
 
   s3Endpoint: process.env.S3_ENDPOINT,
   s3Region: process.env.S3_REGION,

server/config/policies.js

@@ -44,6 +44,7 @@ module.exports.policies = {
 
   '_internal/update-config': ['is-authenticated', 'is-internal'],
 
+  'swagger/show': true,
   'bootstrap/show': true,
   'terms/show': true,
   'access-tokens/create': true,

server/config/routes.js

@@ -235,6 +235,8 @@ module.exports.routes = {
 
   'PATCH /api/_internal/config': '_internal/update-config',
 
+  'GET /swagger.json': 'swagger/show',
+
   'GET /favicons/*': {
     fn: protectedStaticDirServer('/favicons', () => sails.config.custom.faviconsPathSegment),
     skipAssets: false,