verdnatura-mirror
/
loopback
mirror of https://github.com/strongloop/loopback.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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š 2014-01-13 17:02:32 +01:00
parent 191d52995e
commit e6cdeb5cd4
3 changed files with 80 additions and 271 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

255
docs/api-app.md
View File

@ -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).

8
docs/api.md
View File

@ -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)

88
lib/application.js
View File

@ -31,10 +31,10 @@ var DataSource = require('loopback-datasource-juggler').DataSource
* ``` * ```
* *
* @class LoopBackApplication * @class LoopBackApplication
* @header app = loopback() * @header var app = loopback()
*/ */
function App() { 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 * @returns {Array} a list of model classes
*/ */
@ -172,8 +218,28 @@ app.remotes = function () {
return this._remotes || (this._remotes = RemoteObjects.create()); 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) { app.docs = function (options) {
@ -254,7 +320,13 @@ app.enableAuth = function() {
* - `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files * - `cwd` - _optional_ - the directory to use when loading JSON and JavaScript files
* - `models` - _optional_ - an object containing `Model` definitions * - `models` - _optional_ - an object containing `Model` definitions
* - `dataSources` - _optional_ - an object containing `DataSource` 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> * <a name="model-definition"></a>
* **Model Definitions** * **Model Definitions**
* *
@ -314,7 +386,7 @@ app.enableAuth = function() {
* *
* - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors) * - `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 config is not valid
* @throws {Error} If boot fails * @throws {Error} If boot fails
*/ */