Add documentation to your Featherjs services and show them in the Swagger ui.
npm install feathers-swagger --save
npm install feathers feathers-rest feathers-memory feathers-swagger body-parser
Here's an example of a Feathers server that uses feathers-swagger.
const feathers = require('feathers');
const rest = require('feathers-rest');
const memory = require('feathers-memory');
const bodyParser = require('body-parser');
const swagger = require('feathers-swagger');
const messageService = memory();
messageService.docs = {
description: 'A service to send and receive messages',
definitions: {
messages: {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"description": "The message text"
},
"useId": {
"type": "string",
"description": "The id of the user that send the message"
}
}
}
}
};
const app = feathers()
.use(bodyParser.json())
.use(bodyParser.urlencoded({ extended: true }))
.configure(rest())
.configure(swagger({
docsPath: '/docs',
info: {
title: 'A test',
description: 'A description'
}
}))
.use('/messages', messageService);
app.listen(3030);Go to localhost:3030/docs to see the Swagger JSON documentation.
The uiIndex option allows to set a Swagger UI index file which will host the UI at docsPath.
const path = require('path');
const feathers = require('feathers');
const rest = require('feathers-rest');
const memory = require('feathers-memory');
const bodyParser = require('body-parser');
const swagger = require('feathers-swagger');
const messageService = memory();
messageService.docs = {
description: 'A service to send and receive messages',
definitions: {
messages: {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"description": "The message text"
},
"useId": {
"type": "string",
"description": "The id of the user that send the message"
}
}
}
}
};
const app = feathers()
.use(bodyParser.json())
.use(bodyParser.urlencoded({ extended: true }))
.configure(rest())
.configure(swagger({
docsPath: '/docs',
uiIndex: path.join(__dirname, 'docs.html'),
info: {
title: 'A test',
description: 'A description'
}
}))
.use('/messages', messageService);
app.listen(3030);Create a docs.html page like this:
<!DOCTYPE html>
<html>
<head>
<title>Swagger UI</title>
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
<link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
<script src='lib/object-assign-pollyfill.js' type='text/javascript'></script>
<script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='lib/handlebars-4.0.5.js' type='text/javascript'></script>
<script src='lib/lodash.min.js' type='text/javascript'></script>
<script src='lib/backbone-min.js' type='text/javascript'></script>
<script src='swagger-ui.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='lib/marked.js' type='text/javascript'></script>
<script src='lib/swagger-oauth.js' type='text/javascript'></script>
<script type="text/javascript">
$(function () {
var url = "/docs";
hljs.configure({
highlightSizeThreshold: 5000
});
// Pre load translate...
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
window.swaggerUi = new SwaggerUi({
url: url,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function(swaggerApi, swaggerUi){
if(typeof initOAuth == "function") {
initOAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
scopeSeparator: " ",
additionalQueryStringParams: {}
});
}
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
},
onFailure: function(data) {
log("Unable to Load SwaggerUI");
},
docExpansion: "none",
jsonEditor: false,
defaultModelRendering: 'schema',
showRequestHeaders: false
});
$('#input_apiKey').change(function() {
var key = $('#input_apiKey')[0].value;
log("key: " + key);
if(key && key.trim() != "") {
log("added key " + key);
window.authorizations.add("key", new ApiKeyAuthorization("api_key", key, "query"));
}
})
window.swaggerUi.load();
});
</script>
</head>
<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="images/logo_small.png" /><span class="logo__title">swagger</span></a>
</div>
</div>
<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>Now localhost:3030/docs/ will show the documentation in the browser using the Swagger UI.
Copyright (c) 2016
Licensed under the MIT license.