Browse and test your LoopBack app's APIs
Go to file
Miroslav Bajtoš 0b17811546 Generate Swagger Spec 2.0 documentation
Notable breaking changes:

- The swagger output is a single object (JSON response) served
  at /explorer/swagger.json

- Methods with a single return arg without "root:true" flag
  are expected to produce an object response with a single property now,
  i.e. `{ data: arg }`.
  In v1.x, we were treating such arg as if "root:true" was specified.
  The new behaviour matches the actual implementation in strong-remoting.

- The property constraint "length" is translated to "maxLength" now.

- `operationId` includes model name now, because ids must be unique

- X-Forwarded-* headers are no longer processed, Swagger Spec 2.0
  has a way how to specify "use the scheme + host where the doc is served"

- opts.omitProtocolInBaseUrl was removed for the same reasons as
  X-Forwarded-* headers

- The deprecated opts.swaggerDistRoot was removed.
2015-08-21 18:55:32 +02:00
example Merge remote-tracking branch 'upstream/master' into validate_param_enum 2015-07-02 11:03:27 -07:00
lib Generate Swagger Spec 2.0 documentation 2015-08-21 18:55:32 +02:00
public Upgrade to strong-swagger-ui@21.0 (swagger-ui@2.1) 2015-08-13 15:58:35 +02:00
test Generate Swagger Spec 2.0 documentation 2015-08-21 18:55:32 +02:00
.gitignore Merge remote-tracking branch 'upstream/master' into validate_param_enum 2015-07-02 11:03:27 -07:00
.jshintrc Refactoring swagger 1.2 rework. 2014-07-05 14:32:00 -05:00
CHANGES.md Merge remote-tracking branch 'upstream/master' into validate_param_enum 2015-07-02 11:03:27 -07:00
CONTRIBUTING.md Merge remote-tracking branch 'upstream/master' into validate_param_enum 2015-07-02 11:03:27 -07:00
LICENSE Update to dual MIT/StrongLoop license 2014-02-17 16:04:12 -08:00
README.md Rework the module to a loopback component 2015-08-10 16:51:03 +02:00
index.js Generate Swagger Spec 2.0 documentation 2015-08-21 18:55:32 +02:00
package.json Upgrade to strong-swagger-ui@21.0 (swagger-ui@2.1) 2015-08-13 15:58:35 +02:00

README.md

loopback-explorer

Browse and test your LoopBack app's APIs.

Basic Usage

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

var loopback = require('loopback');
var app = loopback();
var explorer = require('../');
var port = 3000;

var Product = loopback.Model.extend('product');
Product.attachTo(loopback.memory());
app.model(Product);

app.use('/api', loopback.rest());

// Register explorer using component-centric API:
explorer(app, { basePath: '/api', mountPath: '/explorer' });
// Alternatively, register as a middleware:
app.use('/explorer', explorer.routes(app, { basePath: '/api' }));

console.log("Explorer mounted at localhost:" + port + "/explorer");

app.listen(port);

Upgrading from v1.x

To upgrade your application using loopback-explorer version 1.x, just replace explorer() with explorer.routes() in your server script:

var explorer = require('loopback-explorer');

// v1.x - does not work anymore
app.use('/explorer', explorer(app, options);
// v2.x
app.use('/explorer', explorer.routes(app, options));

In applications scaffolded by slc loopback, the idiomatic way is to register loopback-explorer via component-config.json:

{
  "loopback-explorer": {
    "mountPath": "/explorer"
  }
}

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', loopback.basicAuth('user', 'password'));
explorer(app, {
  basePath: '/custom-api-root',
  uiDirs: [
    path.resolve(__dirname, 'public'),
    path.resolve(__dirname, 'node_modules', 'swagger-ui')
  ]
  apiInfo: {
    'title': 'My API',
    'description': 'Explorer example app.'
  },
  resourcePath: 'swaggerResources',
  version: '0.1-unreleasable'
}));
app.use('/custom-api-root', loopback.rest());

Options

Options are passed to explorer(app, options).

basePath: String

Default: app.get('restAPIRoot') or '/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 `loopback.use('/custom-api-root', loopback.rest());

mountPath: String

Default: /explorer

Set the path where to mount the explorer component.

protocol: String

Default: null

A hard override for the outgoing protocol (http or https) that is designated in Swagger resource documents. By default, loopback-explorer will write the protocol that was used to retrieve the doc. This option is useful if, for instance, your API sits behind an SSL terminator and thus needs to report its endpoints as https, even though incoming traffic is auto-detected as http.

uiDirs: Array of Strings

Sets a list of paths within your application for overriding Swagger UI files.

If present, will search uiDirs 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. 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.