beauwilliams · September 16, 2025 00:33
diff --git a/swagger.ts b/swagger.ts
 // Why would I use this..?

 // You'd use this approach to avoid the complexity and configuration headaches of standard Swagger UI packages, especially in production. 
 // It's a simple, universal solution to a common deployment problem.

 // Tell me more..?

 // Swagger comes in different packages and flavours (e.g swagger-express, swagger-fastify) with different kinds of configurations, it can be a nightmare to set up, especially when deploying into production where you might need to dockerize your application. 
 // Often a production deployment (i.e via Railway, EC2 etc) requires bundling of the static assets that Swagger UI.
 // This would require configuration of a build tool, or use of a special Docker container with swagger assets bundled in etc.
 // Depending on your framework, your programming language, etc. This process is going to be different every time, leading to many headaches and frictions trying to get Swagger set up in production. 
 // This solution is designed to work across effectively any environment and relies on simply downloading the Swagger assets from the CDN directly and then serving them with a simple rest endpoint.
 // For this example, we are using express, but it can very easily be adopted to any other web framework.

 // How does it work..?

 //Expose your OpenAPI doc
 app.get('/openapi.json', (req, res) => {
  res.json(openApiDocument);
 });

 // Expose your swagger docs endpoint, sending HTML which loads the swagger bundle on the client from CDN
 // Uses SRI hashes and pinned swagger version for security
 app.get('/docs', (req, res) => {
  res.send(`
    <!DOCTYPE html>
    <html lang="en">
    <head>
      <meta charset="UTF-8">
      <title>Provider Check API Documentation</title>
      <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css"
            integrity="sha384-ZJ2d83jl4Lvr6GKYzXpvQUmu+8us6T5frIryNHoLuypLK61jUnnCWZWyyrnifLda"
            crossorigin="anonymous" />
      <style>
        .swagger-ui .topbar { display: none }
      </style>
    </head>
    <body>
      <div id="swagger-ui"></div>
      <script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-bundle.js"
              integrity="sha384-yrdF3mlUytUBwQyEVFAdwuUKEC9Qqrf+IUCgFgho4O5O6irf77pMjv36FN4eTpQD"
              crossorigin="anonymous"></script>
      <script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-standalone-preset.js"
              integrity="sha384-azzkurII4f+bjmZvm3hWhj7JezshyXtwobwneRyWCCIksK61Xi0Ry3xA2am9/TWp"
              crossorigin="anonymous"></script>
      <script>
        window.onload = function() {
          SwaggerUIBundle({
            url: '/openapi.json',
            dom_id: '#swagger-ui',
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            layout: "StandaloneLayout"
          });
        };
      </script>
    </body>
    </html>
  `);
 });
	// Why would I use this..?

	// You'd use this approach to avoid the complexity and configuration headaches of standard Swagger UI packages, especially in production.
	// It's a simple, universal solution to a common deployment problem.

	// Tell me more..?

	// Swagger comes in different packages and flavours (e.g swagger-express, swagger-fastify) with different kinds of configurations, it can be a nightmare to set up, especially when deploying into production where you might need to dockerize your application.
	// Often a production deployment (i.e via Railway, EC2 etc) requires bundling of the static assets that Swagger UI.
	// This would require configuration of a build tool, or use of a special Docker container with swagger assets bundled in etc.
	// Depending on your framework, your programming language, etc. This process is going to be different every time, leading to many headaches and frictions trying to get Swagger set up in production.
	// This solution is designed to work across effectively any environment and relies on simply downloading the Swagger assets from the CDN directly and then serving them with a simple rest endpoint.
	// For this example, we are using express, but it can very easily be adopted to any other web framework.

	// How does it work..?

	//Expose your OpenAPI doc
	app.get('/openapi.json', (req, res) => {
	res.json(openApiDocument);
	});

	// Expose your swagger docs endpoint, sending HTML which loads the swagger bundle on the client from CDN
	// Uses SRI hashes and pinned swagger version for security
	app.get('/docs', (req, res) => {
	res.send(`
	<!DOCTYPE html>
	<html lang="en">
	<head>
	<meta charset="UTF-8">
	<title>Provider Check API Documentation</title>
	<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui.css"
	integrity="sha384-ZJ2d83jl4Lvr6GKYzXpvQUmu+8us6T5frIryNHoLuypLK61jUnnCWZWyyrnifLda"
	crossorigin="anonymous" />
	<style>
	.swagger-ui .topbar { display: none }
	</style>
	</head>
	<body>
	<div id="swagger-ui"></div>
	<script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-bundle.js"
	integrity="sha384-yrdF3mlUytUBwQyEVFAdwuUKEC9Qqrf+IUCgFgho4O5O6irf77pMjv36FN4eTpQD"
	crossorigin="anonymous"></script>
	<script src="https://cdn.jsdelivr.net/npm/[email protected]/swagger-ui-standalone-preset.js"
	integrity="sha384-azzkurII4f+bjmZvm3hWhj7JezshyXtwobwneRyWCCIksK61Xi0Ry3xA2am9/TWp"
	crossorigin="anonymous"></script>
	<script>
	window.onload = function() {
	SwaggerUIBundle({
	url: '/openapi.json',
	dom_id: '#swagger-ui',
	presets: [
	SwaggerUIBundle.presets.apis,
	SwaggerUIStandalonePreset
	],
	layout: "StandaloneLayout"
	});
	};
	</script>
	</body>
	</html>
	`);
	});
No results found