Improve jsdox documentation of app object
Remove docs/api-app.md and docs/api.md, as they are no longer referenced from docs.json. Add few missing bits from docs/api-app.md to lib/application.js comments.
This commit is contained in:
Miroslav Bajtoš
parent
191d52995e
commit
e6cdeb5cd4
255
docs/api-app.md
255
docs/api-app.md
|
|
@ -1,255 +0,0 @@
|
|||
## App object
|
||||
|
||||
The App object represents a Loopback application.
|
||||
|
||||
The App object extends [Express](http://expressjs.com/api.html#express) and supports [Express / Connect middleware](http://expressjs.com/api.html#middleware). See [Express documentation](http://expressjs.com/api.html) for details.
|
||||
|
||||
```js
|
||||
var loopback = require('loopback');
|
||||
var app = loopback();
|
||||
|
||||
app.get('/', function(req, res){
|
||||
res.send('hello world');
|
||||
});
|
||||
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
### models
|
||||
|
||||
The `app.models` object has properties for all defined models. In the following example the `Product` and `CustomerReceipt` models are accessed using the `models` object.
|
||||
|
||||
**NOTE:** you must call `app.boot()` to create the `app.models` object.
|
||||
|
||||
```js
|
||||
var loopback = require('loopback');
|
||||
var app = loopback();
|
||||
app.boot({
|
||||
dataSources: {
|
||||
db: {connector: 'memory'}
|
||||
}
|
||||
});
|
||||
app.model('product', {dataSource: 'db'});
|
||||
app.model('customer-receipt', {dataSource: 'db'});
|
||||
|
||||
// available based on the given name
|
||||
var Product = app.models.Product;
|
||||
|
||||
// also available as camelCase
|
||||
var product = app.models.product;
|
||||
|
||||
// multi-word models are avaiable as pascal cased
|
||||
var CustomerReceipt = app.models.CustomerReceipt;
|
||||
|
||||
// also available as camelCase
|
||||
var customerReceipt = app.models.customerReceipt;
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### app.boot([options])
|
||||
|
||||
Initialize an application from an options object or a set of JSON and JavaScript files.
|
||||
|
||||
**What happens during an app _boot_?**
|
||||
|
||||
1. **DataSources** are created from an `options.dataSources` object or `datasources.json` in the current directory
|
||||
2. **Models** are created from an `options.models` object or `models.json` in the current directory
|
||||
3. Any JavaScript files in the `./models` directory are loaded with `require()`.
|
||||
4. Any JavaScript files in the `./boot` directory are loaded with `require()`.
|
||||
|
||||
**Options**
|
||||
|
||||
- `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files
|
||||
- `models` - _optional_ - an object containing `Model` definitions
|
||||
- `dataSources` - _optional_ - an object containing `DataSource` definitions
|
||||
|
||||
> **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple files may result
|
||||
> in models being **undefined** due to race conditions. To avoid this when using `app.boot()`
|
||||
> make sure all models are passed as part of the `models` definition.
|
||||
|
||||
<a name="model-definition"></a>
|
||||
**Model Definitions**
|
||||
|
||||
The following is an example of an object containing two `Model` definitions: "location" and "inventory".
|
||||
|
||||
```js
|
||||
{
|
||||
"dealership": {
|
||||
// a reference, by name, to a dataSource definition
|
||||
"dataSource": "my-db",
|
||||
// the options passed to Model.extend(name, properties, options)
|
||||
"options": {
|
||||
"relationships": {
|
||||
"cars": {
|
||||
"type": "hasMany",
|
||||
"model": "Car",
|
||||
"foreignKey": "dealerId"
|
||||
}
|
||||
},
|
||||
"remoteMethods": {
|
||||
"nearby": {
|
||||
"description": "Find nearby locations around the geo point",
|
||||
"accepts": [
|
||||
{"arg": "here", "type": "GeoPoint", "required": true, "description": "geo location (lat & lng)"}
|
||||
],
|
||||
"returns": {"arg": "locations", "root": true}
|
||||
}
|
||||
}
|
||||
},
|
||||
// the properties passed to Model.extend(name, properties, options)
|
||||
"properties": {
|
||||
"id": {"id": true},
|
||||
"name": "String",
|
||||
"zip": "Number",
|
||||
"address": "String"
|
||||
}
|
||||
},
|
||||
"car": {
|
||||
"dataSource": "my-db"
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "String",
|
||||
"required": true,
|
||||
"id": true
|
||||
},
|
||||
"make": {
|
||||
"type": "String",
|
||||
"required": true
|
||||
},
|
||||
"model": {
|
||||
"type": "String",
|
||||
"required": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Model definition properties**
|
||||
|
||||
- `dataSource` - **required** - a string containing the name of the data source definition to attach the `Model` to
|
||||
- `options` - _optional_ - an object containing `Model` options
|
||||
- `properties` _optional_ - an object defining the `Model` properties in [LoopBack Definition Language](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language)
|
||||
|
||||
**DataSource definition properties**
|
||||
|
||||
- `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
|
||||
|
||||
### model(name, definition)
|
||||
|
||||
Define a `Model` and export it for use by remote clients.
|
||||
|
||||
**definition**
|
||||
|
||||
- `public` - **default: true** attach the `Model` to the app and export its methods to clients
|
||||
- `dataSource` - **required** the name of the `DataSource` to attach the `Model` to
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// declare a DataSource
|
||||
app.boot({
|
||||
dataSources: {
|
||||
db: {
|
||||
connector: 'mongodb',
|
||||
url: 'mongodb://localhost:27015/my-database-name'
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// describe a model
|
||||
var modelDefinition = {dataSource: 'db'};
|
||||
|
||||
// create the model
|
||||
var Product = app.model('product', modelDefinition);
|
||||
|
||||
// use the model api
|
||||
Product.create({name: 'pencil', price: 0.99}, console.log);
|
||||
```
|
||||
|
||||
**Note** - This will expose all [shared methods](#shared-methods) on the model.
|
||||
|
||||
You may also export an existing `Model` by calling `app.model(Model)` like the example below.
|
||||
|
||||
### models()
|
||||
|
||||
Get the app's exported models. Only models defined using `app.model()` will show up in this list.
|
||||
|
||||
```js
|
||||
var models = app.models();
|
||||
|
||||
models.forEach(function (Model) {
|
||||
console.log(Model.modelName); // color
|
||||
});
|
||||
```
|
||||
|
||||
### docs(options)
|
||||
|
||||
Enable swagger REST API documentation.
|
||||
|
||||
**Options**
|
||||
|
||||
- `basePath` The basepath for your API - eg. 'http://localhost:3000'.
|
||||
|
||||
**Example**
|
||||
|
||||
```js
|
||||
// enable docs
|
||||
app.docs({basePath: 'http://localhost:3000'});
|
||||
```
|
||||
|
||||
Run your app then navigate to [the API explorer](http://petstore.swagger.wordnik.com/). Enter your API basepath to view your generated docs.
|
||||
|
||||
### app.use( router )
|
||||
|
||||
Expose models over specified router.
|
||||
For example, to expose models over REST using the `loopback.rest` router:
|
||||
|
||||
```js
|
||||
app.use(loopback.rest());
|
||||
```
|
||||
|
||||
View generated REST documentation at [http://localhost:3000/_docs](http://localhost:3000/_docs).
|
||||
|
||||
### Middleware
|
||||
|
||||
LoopBack includes middleware similar to [Express / Connect middleware](http://expressjs.com/api.html#middleware).
|
||||
|
||||
#### loopback.token(options)
|
||||
|
||||
**Options**
|
||||
|
||||
- `cookies` - An `Array` of cookie names
|
||||
- `headers` - An `Array` of header names
|
||||
- `params` - An `Array` of param names
|
||||
|
||||
Each array is used to add additional keys to find an `accessToken` for a `request`.
|
||||
|
||||
The following example illustrates how to check for an `accessToken` in a custom cookie, query string parameter
|
||||
and header called `foo-auth`.
|
||||
|
||||
```js
|
||||
app.use(loopback.token({
|
||||
cookies: ['foo-auth'],
|
||||
headers: ['foo-auth', 'X-Foo-Auth'],
|
||||
cookies: ['foo-auth', 'foo_auth']
|
||||
}));
|
||||
```
|
||||
|
||||
**Defaults**
|
||||
|
||||
By default the following names will be checked. These names are appended to any optional names. They will always
|
||||
be checked, but any names specified will be checked first.
|
||||
|
||||
```js
|
||||
params.push('access_token');
|
||||
headers.push('X-Access-Token');
|
||||
headers.push('authorization');
|
||||
cookies.push('access_token');
|
||||
cookies.push('authorization');
|
||||
```
|
||||
|
||||
> **NOTE:** The `loopback.token()` middleware will only check for [signed cookies](http://expressjs.com/api.html#req.signedCookies).
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
## Node.js API
|
||||
|
||||
* [App](#app-object)
|
||||
* [DataSource](#data-source-object)
|
||||
* [GeoPoint](#geopoint-object)
|
||||
* [Model](#model-object)
|
||||
* [Remote methods and hooks](#remote-methods-and-hooks)
|
||||
* [REST API](#rest-api)
|
||||
|
|
@ -31,10 +31,10 @@ var DataSource = require('loopback-datasource-juggler').DataSource
|
|||
* ```
|
||||
*
|
||||
* @class LoopBackApplication
|
||||
* @header app = loopback()
|
||||
* @header var app = loopback()
|
||||
*/
|
||||
function App() {
|
||||
// no op
|
||||
// this is a dummy placeholder for jsdox
|
||||
}
|
||||
|
||||
/*!
|
||||
|
|
@ -122,9 +122,55 @@ app.model = function (Model, config) {
|
|||
}
|
||||
|
||||
/**
|
||||
* Get all exposed models.
|
||||
* Get the models exported by the app. Only models defined using `app.model()`
|
||||
* will show up in this list.
|
||||
*
|
||||
* There are two ways how to access models.
|
||||
*
|
||||
* **1. A list of all models**
|
||||
*
|
||||
* Call `app.models()` to get a list of all models.
|
||||
*
|
||||
* ```js
|
||||
* var models = app.models();
|
||||
*
|
||||
* models.forEach(function (Model) {
|
||||
* console.log(Model.modelName); // color
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* **2. By model name**
|
||||
*
|
||||
* `app.model` has properties for all defined models.
|
||||
*
|
||||
* In the following example the `Product` and `CustomerReceipt` models are
|
||||
* accessed using the `models` object.
|
||||
*
|
||||
* ```js
|
||||
* var loopback = require('loopback');
|
||||
* var app = loopback();
|
||||
* app.boot({
|
||||
* dataSources: {
|
||||
* db: {connector: 'memory'}
|
||||
* }
|
||||
* });
|
||||
*
|
||||
* app.model('product', {dataSource: 'db'});
|
||||
* app.model('customer-receipt', {dataSource: 'db'});
|
||||
*
|
||||
* // available based on the given name
|
||||
* var Product = app.models.Product;
|
||||
*
|
||||
* // also available as camelCase
|
||||
* var product = app.models.product;
|
||||
*
|
||||
* // multi-word models are avaiable as pascal cased
|
||||
* var CustomerReceipt = app.models.CustomerReceipt;
|
||||
*
|
||||
* // also available as camelCase
|
||||
* var customerReceipt = app.models.customerReceipt;
|
||||
* ```
|
||||
*
|
||||
* @header app.models() or app.models.ModelName
|
||||
* @returns {Array} a list of model classes
|
||||
*/
|
||||
|
||||
|
|
@ -172,8 +218,28 @@ app.remotes = function () {
|
|||
return this._remotes || (this._remotes = RemoteObjects.create());
|
||||
}
|
||||
|
||||
/*!
|
||||
* Enable documentation
|
||||
/**
|
||||
* Enable swagger REST API documentation.
|
||||
*
|
||||
* > Note: This method is deprecated, use the extension
|
||||
* [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
|
||||
*
|
||||
* **Options**
|
||||
*
|
||||
* - `basePath` The basepath for your API - eg. 'http://localhost:3000'.
|
||||
*
|
||||
* **Example**
|
||||
*
|
||||
* ```js
|
||||
* // enable docs
|
||||
* app.docs({basePath: 'http://localhost:3000'});
|
||||
* ```
|
||||
*
|
||||
* Run your app then navigate to
|
||||
* [the API explorer](http://petstore.swagger.wordnik.com/).
|
||||
* Enter your API basepath to view your generated docs.
|
||||
*
|
||||
* @deprecated
|
||||
*/
|
||||
|
||||
app.docs = function (options) {
|
||||
|
|
@ -254,7 +320,13 @@ app.enableAuth = function() {
|
|||
* - `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files
|
||||
* - `models` - _optional_ - an object containing `Model` definitions
|
||||
* - `dataSources` - _optional_ - an object containing `DataSource` definitions
|
||||
*
|
||||
*
|
||||
* > **NOTE:** mixing `app.boot()` and `app.model(name, config)` in multiple
|
||||
* > files may result
|
||||
* > in models being **undefined** due to race conditions. To avoid this when
|
||||
* > using `app.boot()`
|
||||
* > make sure all models are passed as part of the `models` definition.
|
||||
*
|
||||
* <a name="model-definition"></a>
|
||||
* **Model Definitions**
|
||||
*
|
||||
|
|
@ -314,7 +386,7 @@ app.enableAuth = function() {
|
|||
*
|
||||
* - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
|
||||
*
|
||||
*
|
||||
* @header app.boot([options])
|
||||
* @throws {Error} If config is not valid
|
||||
* @throws {Error} If boot fails
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue