swaggerize-express, 使用 swagger 2.0和express设计驱动的api

分享于 

8分钟阅读

GitHub

  繁體 雙語
A spec-first approach to building RESTful service with swagger and express.
  • 源代码名称:swaggerize-express
  • 源代码网址:http://www.github.com/krakenjs/swaggerize-express
  • swaggerize-express源代码文档
  • swaggerize-express源代码下载
  • Git URL:
    git://www.github.com/krakenjs/swaggerize-express.git
    Git Clone代码到本地:
    git clone http://www.github.com/krakenjs/swaggerize-express
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/krakenjs/swaggerize-express
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    swaggerize-express

    Build Status
    NPM version

    swaggerize-express 是一种设计驱动方法,使用 Swagger来构建 RESTful api。

    swaggerize-express 提供以下功能:

    • API架构验证。
    • 基于Swagger文档的路由。
    • API文档路径。
    • 输入验证。

    另请参见:

    为什么"设计驱动器""

    已经有许多模块可以帮助 node 构建 RESTful api。 然而,这些模块倾向于将文档或者规范构建为编写应用程序业务逻辑的副作用。

    swaggerize-express 首先从swagger文档开始。 这便于编写更易于设计。评审和测试的api。

    使用生成器快速启动

    本指南将让你从 api.json 到服务项目,无需任何时间。

    首先安装 generator-swaggerize ( 如果你还没有):

    $ npm install -g yo
    $ npm install -g generator-swaggerize

    现在运行生成器。

    $ mkdir petstore &&cd$_$ yo swaggerize

    按照提示( 注意:一定要选择 express 作为你的框架选择)。

    当要求swagger文档时,你可以尝试:

    
    https://raw.githubusercontent.com/wordnik/swagger-spec/master/examples/v2.0/json/petstore.json
    
    
    
    

    现在有了一个工作的api,可以使用像 Swagger UI 这样的东西来探索它。

    手动使用

    var swaggerize =require('swaggerize-express');app.use(swaggerize({
     api:require('./api.json'),
     docspath:'/api-docs',
     handlers:'./handlers'}));

    选项:

    • api - 有效的Swagger 2.0文档。
    • docspath - expose ui的api文档的路径,等等 默认为 /
    • handlers - 路由处理程序的目录结构或者预制的对象( 请参见下面的处理程序对象 )。
    • express - express设置替代。

    使用这里中间件后,将在名为 swaggerapp 上提供一个新属性,其中包含以下属性:

    • api - api文档。
    • routes - 基于api文档的路由定义。

    例如:

    var http =require('http');var express =require('express');var swaggerize =require('swaggerize-express');
    app =express();var server =http.createServer(app);app.use(swaggerize({
     api:require('./api.json'),
     docspath:'/api-docs',
     handlers:'./handlers'}));server.listen(port, 'localhost', function () {
     app.swagger.api.host=server.address().address+':'+server.address().port;
    });

    挂载路径

    Api path 值将以文档值的swagger basePath 为前缀。

    处理程序目录

    options.handlers 选项指定要扫描处理程序的目录。 这些处理程序绑定到swagger文档中定义的api paths

    
    handlers
    
    
     |--foo
    
    
     | |--bar.js
    
    
     |--foo.js
    
    
     |--baz.js
    
    
    
    

    将路由为:

    
    foo.js =>/foo
    
    
    foo/bar.js =>/foo/bar
    
    
    baz.js =>/baz
    
    
    
    

    路径参数

    处理程序目录中的文件和目录名也可以表示路径参数。

    例如要表示路径 /users/{id}:

    handlers
     |--users
     ||--{id}.js

    这也适用于目录名:

    handlers
     |--users
     ||--{id}.js
     ||--{id}
     ||--foo.js

    表示 /users/{id}/foo

    处理程序文件

    每个提供的javascript文件都应该导出一个包含带有HTTP谓词的函数的对象作为键。

    例如:

    module.exports= {
     get:function (req, res) { ... },
     put:function (req, res) { ... },
     ...}

    处理程序中间件

    处理程序还可以通过在谓词下面提供处理程序函数的array 来指定中间件链:

    module.exports= {
     get: [
     functionm1(req, res, next) { ... },
     functionm2(req, res, next) { ... },
     functionhandler(req, res) { ... }
     ],
     ...}

    处理程序对象

    目录生成将产生这个对象,但是它可以直接作为 options.handlers 提供。

    请注意,如果以这种方式构造处理程序对象,则必须命名为 $ 以避免与路径名冲突。 这些键也应该是小写的小写的。

    例如:

    {
     'foo': {
     '$get':function (req, res) { ... },
     'bar': {
     '$get':function (req, res) { ... },
     '$post':function (req, res) { ... }
     }
     }
     ...}

    文件中的处理程序键不存在,不必这样做。

    安全中间件

    如果swagger定义中的路径存在安全定义,并且适当的授权 function exists (defined using x-authorize in the securityDefinitions as per swaggerize-routes ),那么它将被用作该路径的中间件。

    此外,requiredScopes 属性将被注入 request 对象以检查。

    例如:

    Swagger API定义:

    . 
    . 
    . 
    //A route with security object.
     "security": [
     {
     "petstore_auth": [
     "write_pets",
     "read_pets" ]
     }
     ]
    . 
    . 
    . 
    //securityDefinitions
     "securityDefinitions": {
     "petstore_auth": {
     "x-authorize": "lib/auth_oauth.js", //Thispathhastoberelativetotheprojectroot."scopes": {
     "write_pets": "modify pets in your account",
     "read_pets": "read your pets" }
     }
     },

    示例 x-authorize 代码- lib/auth_oauth。js:

    //x-authorize: auth_oauth.jsfunctionauthorize(req, res, next) {
     validate(req, function (error, availablescopes) {
     /* * `req.requiredScopes` is set by the `swaggerize-express` module to help * with the scope and security validation. **/if (!error) {
     for (var i =0; i <req.requiredScopes.length; i++) {
     if (availablescopes.indexOf(req.requiredScopes[i]) >-1) {
     next();
     return;
     }
     }
     error =newError('Do not have the required scopes.');
     error.status=403;
     next(error);
     return;
     }
     next(error);
     });
    }

    authorize的上下文将绑定到安全定义,这样:

    functionauthorize(req, res, next) {
     this.authorizationUrl; //from securityDefinition for this route's type.//...}

    API  EXP  DES  Drive  设计  expr  
    相关文章