sira-express-explorer v0.0.2

sira-express-explorer

Browse and test your Sira app's APIs.

Basic Usage

Below is a simple Sira application. The explorer is mounted at /explorer.

var sira = require('sira');
var express = require('express');
var rest = require('sira-express-rest');
var explorer = require('../');
var port = 3000;

// create express application
var app = express();
app.disable('x-powered-by');

// create sira application
var sapp = sira();
sapp.registry.define('Product', {crud: true});
sapp.phase(sira.boot.database());
sapp.boot(function (err) { if (err) throw err; });

// setup middlewares
var apiPath = '/api';
app.use('/explorer', explorer(sapp, { basePath: apiPath }));
app.use(apiPath, rest(sapp));
console.log("Explorer mounted at localhost:" + port + "/explorer");

// start server
app.listen(port);

Advanced Usage

Many aspects of the explorer are configurable.

See options for a description of these options:

// Mount middleware before calling `explorer()` to add custom headers, auth, etc.
app.use('/explorer', basicAuth('user', 'password'));
app.use('/explorer', explorer(sapp, {
  basePath: '/custom-api-root',
  swaggerDistRoot: '/swagger',
  apiInfo: {
    'title': 'My API',
    'description': 'Explorer example app.'
  },
  resourcePath: 'swaggerResources',
  version: '0.1-unreleasable'
}));
app.use('/custom-api-root', rest(sapp));

Options

Options are passed to explorer(sapp, options).

basePath: String

Default: '/api'.

Sets the API's base path. This must be set if you are mounting your api to a path different than '/api', e.g. with `app.use('/custom-api-root', rest(sapp));

swaggerDistRoot: String

Sets a path within your application for overriding Swagger UI files.

If present, will search swaggerDistRoot first when attempting to load Swagger UI, allowing you to pick and choose overrides to the interface. Use this to style your explorer or add additional functionality.

See index.html, where you may want to begin your overrides. The rest of the UI is provided by Swagger UI.

apiInfo: Object

Additional information about your API. See the spec.

resourcePath: String

Default: 'resources'

Sets a different path for the [resource listing](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#51-resource-listing). You generally shouldn't have to change this.

version: String

Default: Read from package.json

Sets your API version. If not present, will read from your app's package.json.