This is a Swagger UI plug-in for HAPI. When installed it will self document HTTP API interface in a project.
You can add the module to your HAPI using npm:
$ npm install hapi-swagger --save,
In the .js file where you create the HAPI server object add the following code after you have created the server object:
var pack = require('../package'),
swaggerOptions = {
basePath: 'http://localhost:8000',
apiVersion: pack.version
};
server.pack.require({'hapi-swagger': swaggerOptions}, function (err) {
if (!err && err !== null) {
server.log(['error'], 'Plugin "hapi-swagger" load error: ' + err)
}else{
server.log(['start'], 'swagger interface loaded')
}
});
As a project may be a mixture of web pages and API endpoints you need to tag the routes you wish Swagger to document. Simply add the tags: ['api'] property to the route object for any endpoint you want documenting.
{
method: 'GET',
path: '/todo/{id}/',
config: {
handler: handlers.mapUsername,
description: 'Get todo',
notes: 'Returns a todo item by the id passed in the path',
tags: ['api'],
validate: {
path: {
username: joi.number()
.required()
.description('the id for the todo item'),
}
}
},
}
The plugin adds all the resources needed to build the interface into your project. All you need to do is add some javascript into the header of a web page and add two elements into the HTML where you wish it to render.
The doc directory and all the files in the URLs below are added by the plugin
<link href='https://fonts.googleapis.com/css?family=Droid+Sans:400,700' rel='stylesheet' type='text/css'/>
<link href='/docs/swaggerui/css/highlight.default.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='/docs/swaggerui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<script src="/docs/swaggerui/lib/shred.bundle.js" type="text/javascript"></script>
<script src='/docs/swaggerui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/handlebars-1.0.0.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/underscore-min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/backbone-min.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/swagger.js' type='text/javascript'></script>
<script src='/docs/swaggerui/swagger-ui.js' type='text/javascript'></script>
<script src='/docs/swaggerui/lib/highlight.7.3.pack.js' type='text/javascript'></script>
<script type="text/javascript">
$(function () {
window.swaggerUi = new SwaggerUi({
url: window.location.protocol + '//' + window.location.host + '/docs',
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
onComplete: function(swaggerApi, swaggerUi){
log("Loaded SwaggerUI")
$('pre code').each(function(i, e) {hljs.highlightBlock(e)});
},
onFailure: function(data) {
log("Unable to Load SwaggerUI");
},
docExpansion: "list"
});
window.swaggerUi.load();
});
</script>
Place the HTML code below into the body fo web page where you wish the interface to render
<section id="swagger">
<h1 class="entry-title api-title">API</h1>
<div id="message-bar" class="swagger-ui-wrap"></div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</section>
HAPI allow you to define a response object for an API endpoint. The response object is used by HAPI to both validation and description the output of an API. It uses the same JOI validation objects to describe the input parameters. The plugin turns these object into visual description and examples in the Swagger UI.
An very simple example of the use of the response object:
var responseModel = hapi.types.object({
equals: joi.number(),
}).options({
className: 'Result'
});
within you route object ...
config: {
handler: handlers.add,
description: 'Add',
tags: ['api'],
notes: ['Adds together two numbers and return the result'],
validate: {
path: {
a: joi.number()
.required()
.description('the first number'),
b: joi.number()
.required()
.description('the second number')
}
},
response: {schema: responseModel}
}
A working demo of more complex uses of response object can be found in the be-more-hapi project.
You can add HTTP error status codes to each of the endpoints. As HAPI routes don not directly have a property for error status codes so you need to add them to the notes. The status codes need to be added to the end of the notes array starting with array item with the value "Error status codes". Each error code should be added as string with code first follow by its description:
config: {
handler: handlers.add,
description: 'Add',
tags: ['api'],
jsonp: 'callback',
notes: [
'Adds together two numbers and return the result',
'Error status codes',
'400, bad request'
],
validate: {
path: {
a: joi.number()
.required()
.description('the first number'),
b: joi.number()
.required()
.description('the second number')
}
}
}
The project has a small number integration and unit tests. To run the test within the project type the following command.
$ mocha --reporter list
If you are considering sending a pull request please add tests for the functionality you add or change.
I would like to thank Brandwatch who allow me to open this code up as part of the work on this plugin was done during a contract with them.
- Joshua McGinnis (https://github.com/joshua-mcginnis)
- David Waterston (https://github.com/davidwaterston)
- Jozz (https://github.com/jozzhart)
- John Oliva (https://github.com/joliva)
- thiagogalesi4e (https://github.com/thiagogalesi4e)
- HughePaul (https://github.com/HughePaul)
If you find any issue please file here on github and I will try and fix them.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent