feathers-swagger

Add documentation to your Featherjs services and feed them to Swagger UI.

Please see the example below.

Getting Started

To install feathers-swagger from npm, run:

$ npm install feathers-swagger --save

Finally, to use the plugin in your Feathers app:

// Require
var feathers = require('feathers');
var feathersSwagger = require('feathers-swagger');
// Setup
var app = feathers();

/* ===== Important: Feathers-Swagger part below ===== */
// Use Feathers Swagger Plugin
app.configure(feathersSwagger({ 
/* example configuration */ 
    docsPath:'/docs',
    version: '0.0.0',
    basePath: '/api',
    info: {
        'title': 'API',
        'description': 'This is an API.',
        'termsOfServiceUrl': 'https://github.com/feathersjs/feathers-swagger/blob/master/LICENSE',
        'contact': 'example@example.com',
        'license': 'MIT',
        'licenseUrl': 'https://github.com/feathersjs/feathers-swagger/blob/master/LICENSE'
    }
}));

// Add your service(s)
app.use('/examples', {
    
    // Standard `find` method for a sevice.
    // Will automatically detect that `find` is available and create documentation for it.
    find: function(params, callback) {
        callback([]);
    },
    
    /*
    // The following methods will not be added to documentation,
    // because they are commented out and so do not exist for this service.
    get: function(id, params, callback) {
        callback({});
    },
    create: function(data, params, callback) {
        callback({});
    },
    update: function(id, data, params, callback) {
        callback({});
    },
    remove: function(id, params, callback) {
        callback({});
    },
    */
    
    // Below is optional: showing the more advanced customization options.
    docs: {
        description: "Operations about examples.",
        find: {
            type: 'Example',
            parameters: [{
                name: 'name',
                description: 'Filter Examples by name.',
                required: false,
                type: 'string',
                paramType: 'form'
            }],
            errorResponses: [
                {
                    code: 500,
                    reason: 'Example error.'
                }
            ]
        },
        models: {
            Example: {
                id: 'Example',
                description: 'This is an Example model.',
                required: ['name'],
                properties: {
                    name: { 
                        type: 'string',
                        description: 'This is the example name.'
                    },
                    anotherProperty: {
                        type:'string',
                        description: 'This is the example description.'
                    }
                }
            }
        }
    }
});

// Finally, start your server.
app.listen(3000, function(){
    console.log('Feathers server listening on port '+port+'.');
});

To view, go to the Swagger UI demo at http://swagger.wordnik.com/ and change the base url from http://petstore.swagger.wordnik.com/api/api-docs to http://localhost:3000/api/docs

Example

See the example directory for example source code.

To run the example, see the Contributing instructions below.

The following screenshot was created with the example.

Documentation

See the docs directory.

Contributing

Clone this repository and run the following:

Install Dependencies

npm install
bower install

Run for Development

grunt develop

Author

Glavin Wiechert

License

Licensed under the MIT license.

robotnic/feathers-swagger