Feb 16, 2021
API Documentation using AWS S3 and Swagger-UI
Open-API is one of the most popular specifications for documenting API’s to date. Swagger provide many useful tools to help you document using the Open-API specification.
In a recent challenge we wished to open our existing swagger documentation up to the public, in a cost-effective and self managed way. That got me thinking…
💡 — Use one of Amazons mature cloud services; AWS S3
In this article I will show you the way we documented our API on S3 in a simple NodeJS project using WebpackJS and Swagger-UI. There is a much simpler way to achieve the same outcome using ‘Swagger-UI-dist’ — everything you need for SwaggerUI to function without having to configure any project (see a post by Kevin Mun here 👏).
We went down the route of creating a NodeJS project to make it safe to update the Swagger-UI version in the future and have the built in package manager to do this for us.
Not only that but we can also use Webpack’s HTML plugin to design a template to customise our documentation and tailor it to our stakeholders whilst keeping our templating completely separate from Swagger-UI and any future updates that would affect the integrity of the documentation.
Getting Started 🚀
Initialise the NodeJS package manager with npm init:
npm init…and install the following developer dependencies
npm install css-loader json-loader style-loader yaml-loader webpack webpack-cli html-webpack-plugin -D…and the main dependency
npm install swagger-uiYour project should now look like this:
Writing some code 🤓
In the project root, create a folder named ‘src’. Here’s where we’ll keep our source code to interact with Swagger-UI and also our key ingredient our Swagger YAML/JSON template.
In src create an index.js file and also add your Swagger template there too in YAML or JSON format.
Add the following code to index.js
const SwaggerUI = require('swagger-ui');
require('swagger-ui/dist/swagger-ui.css');const spec = require('./swagger-config.yaml');SwaggerUI({
spec,
dom_id: '#swagger',
});
We instantiate the SwaggerUI class and inject our specification ‘spec’ into it. The ‘dom_id’ property tells the component to render the documentation into a HTML attribute with the ID ‘swagger’, more on this later…
Finishing touches
So now we’ve got our code set up, we need to use Webpack to bundle this into a script that can be used on our index.html on AWS S3.
At the root create an index.html file — this will act as our template that we can customise to provide a better experience for our customers and stakeholders.
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<title>Our API Documentation</title>
</head>
<body>
<!-- Custom HTML/navigation can be placed here -->
<div id="swagger"></div>
</body>
</html>Note: we have now created our HTML ‘dom_id’ element with the id of ‘swagger’ that we injected into our SwaggerUI object above. The values must match, and could be labelled anything you like
Also in the root, create a webpack.config.js file — this will tell webpack exactly how we wish to bundle the code and build the project.
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');const outputPath = path.resolve(__dirname, 'dist');module.exports = {
mode: 'development',
entry: {
// tell webpack where our code is
app: './src/index.js',
},
module: {
rules: [{
test: /\.yaml$/,
use: [
{ loader: 'json-loader' },
{ loader: 'yaml-loader' }
]
},
{
test: /\.css$/,
use: [
{ loader: 'style-loader' },
{ loader: 'css-loader' },
]
}]
},
plugins: [
// tell webpack to use our template we created
new HtmlWebpackPlugin({
template: 'index.html'
})
],
// tell webpack where to output the build code to - './dist'
output: {
filename: '[name].bundle.js',
path: outputPath,
}
};
Now you’re complete project will look like this:
Build and deploying
Before pushing our code to S3 we need to actually execute webpack to bundle our code. To do this in package.json add the following to the script section:
"scripts": {
"build": "webpack"
},… and run in a terminal ‘npm run build’. This will create our built distribution to upload to S3.
Now with AWS CLI access, run the following to upload the code to S3:
aws s3 cp ./dist s3://<BUCKET_NAME> — recursiveNote: these commands are best built into a CI/CD pipeline to run automatically for you on a schema change/source control repository merge request.
S3 configuration
Okay now we’ve got our static content into S3, time to configure the bucket. For purposes of this article we shall do this manually.
For production environments consider using tools like Serverless framework, AWS SAM, Terraform etc so that you can replicate across another AWS subscription without any manual steps, see ‘Infrastructure as Code’.
In the S3 Console — select your bucket → properties and scroll to the bottom for ‘Static Website Hosting’.
Enable static web hosting and point the index document to our index.html file in our bucket.
Before hitting save, consider the following AWS information notice about making your objects publicly readable, otherwise the user will see a HTTP status code 403 Forbidden. Access must be public to grant access to the web in order for end users to view the schema, if you wanted to tie down access to certain IP addresses, referrer headers or other security schemes you can configure a bucket policy.
And we’re DONE! 🎉
View your API schema online using one of the easiest and cheapest methods of web hosting. Simply go to http://<BUCKET_NAME>.s3-website-<REGION>.amazonaws.com/
I hope the above tutorial has helped you make your API documentation publicly accessible.
Happy building!… 🚀
Thank you for reading, Robert.
Reach me on linkedIn here: https://www.linkedin.com/in/robertbulmer/
