Azure Node Functions Apps and OpenAPI Swagger

Paul Sterl — Sun, 12 Mar 2023 09:15:26 +0000

Sometimes we face the problem that we want to host a very simple web-service including a swagger-ui / OpenApi-UI. The question now is, what is the simplest solution, which works everywhere, even in a azure function app?

Where are of course some libs etc. which on the other hand require us to run the web-server. If we look into the doc using the simple unpkg HTML files looks like to be the simplest solution.




  
  
  
  SwaggerUI

What needs to be done

Get the HTML OpenAPI HTML file
Provide an OpenAPI YML or JSON
Create an endpoint which should host the doc

This solution works also for a spring web app or a AWS function. We will go ahead and look into a Node JavaScript example to see how it may look like:

Which means we have to create a new azure function endpoint where we want to host the OpenApi-UI:

function.json

We can set the function to „anonymous“ if we like and only get is required:

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

openApi.html

The only adjustment to the original HTML file is the source of the yml or json file. You could also adjust the JS and CSS url:




  
  
  
  SwaggerUI

openApi.yml

Just as an example here. Note here the URL which has a funny value of _server.url_, we will replace this value later.

openapi: 3.0.2
info:
  title: My OpenAPI
  version: v1
servers:
  - url: "_server.url_"
paths:
  /foo:
    get:
      summary: Som cool function
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                type: string

index.js

"use strict";
const fs = require('fs');
const util = require('util');
const readFileAsync = util.promisify(fs.readFile);

module.exports = async function (context, req) {
    switch(req.query.file) {
        case 'openApi.yml':
            // get the url and remove the doc suffix, azure specific
            const url = req.headers.referer.replace('/doc', '');
            let yml = await readFileAsync('doc/openApi.yml', 'UTF-8');
            yml = yml.replace('_server.url_', url);
            context.res = {
                body: yml,
                headers: {
                    "Content-Type": "application/yml; charset=utf-8"
                }
            };
            break;
        default:
            context.res = {
                body: await readFileAsync('doc/openApi.html', 'UTF-8'),
                headers: {
                    "Cache-Control": "max-age=600", // optional cache header
                    "Content-Type": "text/html; charset=utf-8"
                }
            };
            break;
    }
}

The switch case is where to ensure we load only files we want to publish, as so you have to extend the case block if you want to host the JS files too. Of course they have to be added to your directory.