зеркало из https://github.com/Azure/sway.git
An attempt at Markdown-based documentation
This commit is contained in:
Jeremy Whitlock
Родитель
24147b5fc7
Коммит
4b0cde5462
|
|
@ -0,0 +1,115 @@
|
|||
## Classes
|
||||
<dl>
|
||||
<dt><a href="#Operation">Operation</a></dt>
|
||||
<dd></dd>
|
||||
<dt><a href="#Parameter">Parameter</a></dt>
|
||||
<dd></dd>
|
||||
<dt><a href="#SwaggerApi">SwaggerApi</a></dt>
|
||||
<dd></dd>
|
||||
</dl>
|
||||
## Functions
|
||||
<dl>
|
||||
<dt><a href="#create">create(options, [callback])</a> ⇒ <code>Promise</code></dt>
|
||||
<dd><p>Creates a SwaggerApi object from its Swagger definition(s).</p>
|
||||
</dd>
|
||||
</dl>
|
||||
<a name="Operation"></a>
|
||||
## Operation
|
||||
**Kind**: global class
|
||||
|
||||
* [Operation](#Operation)
|
||||
* [new Operation(path, method, ptr, definition, parameters)](#new_Operation_new)
|
||||
* [.getParameters()](#Operation+getParameters) ⇒ <code>[Array.<Parameter>](#Parameter)</code>
|
||||
|
||||
<a name="new_Operation_new"></a>
|
||||
### new Operation(path, method, ptr, definition, parameters)
|
||||
The Swagger Operation object.
|
||||
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| path | <code>string</code> | The operation path |
|
||||
| method | <code>string</code> | The operation method |
|
||||
| ptr | <code>string</code> | The JSON Pointer to the operation |
|
||||
| definition | <code>object</code> | The operation definition |
|
||||
| parameters | <code>[Array.<Parameter>](#Parameter)</code> | The Swagger parameter objects |
|
||||
|
||||
<a name="Operation+getParameters"></a>
|
||||
### operation.getParameters() ⇒ <code>[Array.<Parameter>](#Parameter)</code>
|
||||
Returns all parameters for the operation.
|
||||
|
||||
**Kind**: instance method of <code>[Operation](#Operation)</code>
|
||||
**Returns**: <code>[Array.<Parameter>](#Parameter)</code> - All parameters for the operation.
|
||||
<a name="Parameter"></a>
|
||||
## Parameter
|
||||
**Kind**: global class
|
||||
<a name="new_Parameter_new"></a>
|
||||
### new Parameter(ptr, definition)
|
||||
The Swagger Parameter object.
|
||||
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| ptr | <code>string</code> | The JSON Pointer to the parameter |
|
||||
| definition | <code>object</code> | The parameter definition |
|
||||
|
||||
<a name="SwaggerApi"></a>
|
||||
## SwaggerApi
|
||||
**Kind**: global class
|
||||
|
||||
* [SwaggerApi](#SwaggerApi)
|
||||
* [new SwaggerApi(definition, version, documentation, operations, options)](#new_SwaggerApi_new)
|
||||
* [.getOperation(path, method)](#SwaggerApi+getOperation) ⇒ <code>[Operation](#Operation)</code>
|
||||
* [.getOperations([path])](#SwaggerApi+getOperations) ⇒ <code>[Array.<Operation>](#Operation)</code>
|
||||
|
||||
<a name="new_SwaggerApi_new"></a>
|
||||
### new SwaggerApi(definition, version, documentation, operations, options)
|
||||
The Swagger API object.
|
||||
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| definition | <code>object</code> | The Swagger definition |
|
||||
| version | <code>string</code> | The Swagger definition version |
|
||||
| documentation | <code>string</code> | The Swagger Specification documentation URL |
|
||||
| operations | <code>[Array.<Operation>](#Operation)</code> | The Swagger operation objects |
|
||||
| options | <code>object</code> | The options passed to swaggerApi.create |
|
||||
|
||||
<a name="SwaggerApi+getOperation"></a>
|
||||
### swaggerApi.getOperation(path, method) ⇒ <code>[Operation](#Operation)</code>
|
||||
Returns the operation for the provided path and method.
|
||||
|
||||
**Kind**: instance method of <code>[SwaggerApi](#SwaggerApi)</code>
|
||||
**Returns**: <code>[Operation](#Operation)</code> - The operation for the provided path and method or undefined if there is no operation for that
|
||||
path and method combination.
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| path | <code>string</code> | The Swagger path |
|
||||
| method | <code>string</code> | The Swagger operation method |
|
||||
|
||||
<a name="SwaggerApi+getOperations"></a>
|
||||
### swaggerApi.getOperations([path]) ⇒ <code>[Array.<Operation>](#Operation)</code>
|
||||
Returns all operations for the provided path or all operations in the API.
|
||||
|
||||
**Kind**: instance method of <code>[SwaggerApi](#SwaggerApi)</code>
|
||||
**Returns**: <code>[Array.<Operation>](#Operation)</code> - All operations for the provided path or all API operations.
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| [path] | <code>string</code> | The Swagger path |
|
||||
|
||||
<a name="create"></a>
|
||||
## create(options, [callback]) ⇒ <code>Promise</code>
|
||||
Creates a SwaggerApi object from its Swagger definition(s).
|
||||
|
||||
**Kind**: global function
|
||||
**Returns**: <code>Promise</code> - A promise is always returned even if you provide a callback but it is not required to be used
|
||||
|
||||
| Param | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| options | <code>object</code> | The options for loading the definition(s) |
|
||||
| [options.loaderOptions] | <code>object</code> | The options to pass to path-loader |
|
||||
| options.definition | <code>object</code> | <code>string</code> | The Swagger definition location or structure |
|
||||
| [callback] | <code>function</code> | Node.js error-first callback |
|
||||
|
||||
172
docs/README.md
172
docs/README.md
|
|
@ -39,178 +39,10 @@ Installation for Node.js applications can be done via [NPM][npm].
|
|||
npm install swagger-core-api --save
|
||||
```
|
||||
|
||||
## API Types
|
||||
## API Documentation
|
||||
|
||||
The swagger-core-api exposes a few JavaScript objects and their documentation is below.
|
||||
|
||||
### Operation
|
||||
|
||||
This object represents a Swagger operation.
|
||||
|
||||
#### properties
|
||||
|
||||
This object has all of the properties set on the Swagger operation defintion as well as the properties provided below.
|
||||
|
||||
##### path {string}
|
||||
|
||||
This is the Swagger operation path.
|
||||
|
||||
##### method {string}
|
||||
|
||||
This is the Swagger operation method.
|
||||
|
||||
##### ptr {string}
|
||||
|
||||
This is the [JSON Pointer][json-pointer] to the location in the Swagger definition document where the operation is
|
||||
defined.
|
||||
|
||||
##### definition {object}
|
||||
|
||||
This is the Swagger operation definition. _(Note: The `parameters` and `security` properties are composites that
|
||||
represent the applied equivalent. So for `parameters`, this includes path-level parameters and for `security`, this
|
||||
includes global security if available and there is no explicit security described.)_
|
||||
|
||||
#### functions
|
||||
|
||||
##### getParameters()
|
||||
|
||||
##### Returns
|
||||
|
||||
Returns a `Parameter[]` for the given operation.
|
||||
|
||||
### Parameter
|
||||
|
||||
This object represents a Swagger operation parameter.
|
||||
|
||||
#### properties
|
||||
|
||||
This object has all of the properties set on the Swagger operation parameter defintion as well as the properties
|
||||
provided below.
|
||||
|
||||
##### ptr {string}
|
||||
|
||||
This is the [JSON Pointer][json-pointer] to the location in the Swagger definition document where the operation
|
||||
parameter is defined.
|
||||
|
||||
##### definition {object}
|
||||
|
||||
This is the Swagger operation parameter definition.
|
||||
|
||||
### SwaggerApi
|
||||
|
||||
This object represents the Swagger definition document.
|
||||
|
||||
#### properties
|
||||
|
||||
This object has all of the properties set on the Swagger document defintion as well as the properties provided below.
|
||||
|
||||
##### definition {object}
|
||||
|
||||
This is the JavaScript object representing your Swagger definition
|
||||
|
||||
##### documentation {string}
|
||||
|
||||
This is the URL to the Swagger Specification document for the Swagger version your SwaggerApi object corresponds to.
|
||||
|
||||
##### options {object}
|
||||
|
||||
This is the options object passed to `SwaggerApi.load`.
|
||||
|
||||
##### version {string}
|
||||
|
||||
This is the Swagger version for the provided Swagger definition document.
|
||||
|
||||
#### functions
|
||||
|
||||
##### getOperations([path])
|
||||
|
||||
###### Arguments
|
||||
|
||||
####### path {string}
|
||||
|
||||
This is the optional Swagger operation path to filter the operations by.
|
||||
|
||||
###### Returns
|
||||
|
||||
This API always returns an `Operation[]`. If no `path` is provided, all operations are returned. If a path is
|
||||
provided, all operations for the given `path` are returned.
|
||||
|
||||
##### getOperation(path, method)
|
||||
|
||||
###### Arguments
|
||||
|
||||
####### path {string}
|
||||
|
||||
This is the Swagger operation path
|
||||
|
||||
####### method {string}
|
||||
|
||||
This is the Swagger operation method
|
||||
|
||||
###### Returns
|
||||
|
||||
Returns the `Operation` for the provided `path` and `method` combination or `undefined` if no operation matches those
|
||||
criteria.
|
||||
|
||||
## API
|
||||
|
||||
swagger-core-api exposes a single function for creating the `SwaggerApi` object. Depending on your, environment,
|
||||
how you call this function changes. For the browser, swagger-core-api is exposed as `SwaggerApi`. Of course, in
|
||||
Node.js it depends on which variable you assign the swagger-core-api module to. For consistency, all examples you see
|
||||
assume you've named your Node.js variable `SwaggerApi` like this:
|
||||
|
||||
```js
|
||||
var SwaggerApi = require('swagger-core-api');
|
||||
```
|
||||
|
||||
### load(options, [callback])
|
||||
|
||||
#### Arguments
|
||||
|
||||
##### options {object}
|
||||
|
||||
This argument is required and its content are the options necessary for swagger-core-api, and its upstream dependencies,
|
||||
to work. Below are the keys and their purpose:
|
||||
|
||||
* `{object} [loaderOptions]`: This is the options that get passed to [path-loader][path-loader] when retrieving Swagger
|
||||
definitions from the filesystem or a URL. Right now it supports the `method` property _({string}, used to dictate which
|
||||
HTTP method to use for remote http/https URLs)_ and the `prepareRequest` property _({function}, used to prepare the
|
||||
HTTP request for remote http/https URLs for things like authentication/authorization)_.
|
||||
* `{object|string} definition`: This is the path/URL to your Swagger definition or the Swagger definition in JavaScript object
|
||||
form
|
||||
|
||||
##### callback {function}
|
||||
|
||||
This is an optional error-first callback.
|
||||
|
||||
##### Returns {Promise}
|
||||
|
||||
This API **always** returns a `Promise`, even if you provide a callback.
|
||||
|
||||
##### Example _(Promise)_
|
||||
|
||||
```js
|
||||
SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml')
|
||||
.then(function (api) {
|
||||
console.log('Documentation URL: ', api.documentation);
|
||||
}, function (err) {
|
||||
console.error(err.stack);
|
||||
});
|
||||
```
|
||||
|
||||
##### Example _(Callback)_
|
||||
|
||||
```js
|
||||
SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml', function (err, api) {
|
||||
if (err) {
|
||||
console.error(err.stack);
|
||||
} else {
|
||||
console.log('Documentation URL: ', api.documentation);
|
||||
});
|
||||
```
|
||||
The swagger-core-api project's API documentation can be found here: https://github.com/apigee-127/swagger-core-api/blob/master/docs/API.md
|
||||
|
||||
[bower]: http://bower.io/
|
||||
[json-pointer]: https://tools.ietf.org/html/rfc6901
|
||||
[npm]: https://www.npmjs.org/
|
||||
[path-loader]: https://github.com/whitlockjc/path-loader
|
||||
[swagger]: http://swagger.io
|
||||
|
|
|
|||
14
gulpfile.js
14
gulpfile.js
|
|
@ -25,12 +25,14 @@
|
|||
'use strict';
|
||||
|
||||
var browserify = require('browserify');
|
||||
var concat = require("gulp-concat");
|
||||
var del = require('del');
|
||||
var eslint = require('gulp-eslint');
|
||||
var exposify = require('exposify');
|
||||
var fs = require('fs');
|
||||
var gulp = require('gulp');
|
||||
var istanbul = require('gulp-istanbul');
|
||||
var jsdoc2Md = require('gulp-jsdoc-to-markdown');
|
||||
var mocha = require('gulp-mocha');
|
||||
var mochaPhantomJS = require('gulp-mocha-phantomjs');
|
||||
var runSequence = require('run-sequence');
|
||||
|
|
@ -242,10 +244,20 @@ gulp.task('test-browser', ['browserify'], function () {
|
|||
});
|
||||
});
|
||||
|
||||
gulp.task('docs', function () {
|
||||
return gulp.src([
|
||||
'./index.js',
|
||||
'lib/*.js'
|
||||
])
|
||||
.pipe(concat('API.md'))
|
||||
.pipe(jsdoc2Md())
|
||||
.pipe(gulp.dest('docs'));
|
||||
});
|
||||
|
||||
gulp.task('test', function (cb) {
|
||||
runSequence('test-node', 'test-browser', cb);
|
||||
});
|
||||
|
||||
gulp.task('default', function (cb) {
|
||||
runSequence('lint', 'test', cb);
|
||||
runSequence('lint', 'test', 'docs', cb);
|
||||
});
|
||||
|
|
|
|||
|
|
@ -34,8 +34,10 @@
|
|||
"del": "^1.1.1",
|
||||
"exposify": "^0.4.0",
|
||||
"gulp": "^3.8.11",
|
||||
"gulp-concat": "^2.5.2",
|
||||
"gulp-eslint": "^0.8.0",
|
||||
"gulp-istanbul": "^0.8.1",
|
||||
"gulp-jsdoc-to-markdown": "^1.1.1",
|
||||
"gulp-mocha": "^2.0.1",
|
||||
"gulp-mocha-phantomjs": "^0.6.1",
|
||||
"run-sequence": "^1.1.0",
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче