Add swagger page to restify

Question

I have a restify server (typescript) and want to add swagger documentation to it. I've tried various npm packages but I didn't manage to get one of them running correctly.

restify-swagger-jsdoc

This is the closest one working. I can create a swagger page with it. Unfortunately there's a bug so that always the demo petstore is being loaded. This seems to be due it's outdated, see this bugreport.

I used the following code:

import restify from "restify";
import * as swagger from "restify-swagger-jsdoc"

const server = restify.createServer();
server.use(restify.plugins.bodyParser());

swagger.createSwaggerPage({
    title: 'API documentation',
    version: '1.0.0',
    server: server,
    path: '/docs',
    apis: ['./src/server.ts']
});

swagger-jsdoc & swagger-ui

Using the following code:

import restify from "restify";
import swaggerJSDoc from "swagger-jsdoc";
import SwaggerUI from "swagger-ui";

const server = restify.createServer();
server.use(restify.plugins.bodyParser());

const swaggerSpec = swaggerJSDoc({
    definition: {
        openapi: '3.1.0',
        info: {
            title: 'API Documentation',
            version: '1.0.0'
        }
    },
    apis: ['./src/server.ts']
})
const swaggerUi = SwaggerUI({
    spec: swaggerSpec,
    dom_id: '#swagger'
})

Results in:

project_name\node_modules\react-syntax-highlighter\dist\esm\light.js:1
import highlight from './highlight';
^^^^
SyntaxError: Cannot use import statement outside a module

Google tells me to set the type: "module" within the package.json. This on the other hand leads to:

Object.defineProperty(exports, "__esModule", { value: true });
ReferenceError: exports is not defined in ES module scope

Google says the solution for this would be to set the type: "commonjs" in the package.json. Obviously this is no solution for me, as it leads again to the first exception.

swagger-jsdoc & swagger-ui-dist

Using the following code:

import restify from "restify";
import swaggerJSDoc from "swagger-jsdoc";
import {absolutePath as pathToSwaggerUi, SwaggerUIBundle} from "swagger-ui-dist";

const server = restify.createServer();
server.use(restify.plugins.bodyParser());

const swaggerSpec = swaggerJSDoc({
    definition: {
        openapi: '3.1.0',
        info: {
            title: 'API Documentation',
            version: '1.0.0'
        }
    },
    apis: ['./src/server.ts']
})
const ui = SwaggerUIBundle({
    spec: swaggerSpec,
    dom_id: '#swagger',
    presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
})

Results in an output of the entire content of swagger-ui-bundle.js in the console, followed by ReferenceError: window is not defined when trying to start the server.

Answer 1

I also encountered the bug for restify-swagger-jsdoc. You can use the version 3.2.2 of restify-swagger-jsdoc. It worked just fine for me, just use your current code for it and it should work fine.