酷徒LOGO

koa-oai-router, 在 OpenAPI Swagger和Json模式上,Koa路由器,基于


  • 源代码名称:koa-oai-router
  • 源代码网址:http://www.github.com/BiteBit/koa-oai-router
  • koa-oai-router源代码文档
  • koa-oai-router源代码下载
  • Git URL:
    git://www.github.com/BiteBit/koa-oai-router.git
    Git Clone代码到本地:
    git clone http://www.github.com/BiteBit/koa-oai-router
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/BiteBit/koa-oai-router
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    Koa-OAI-Router

    LicenseNode VersionNPM VersionBuild StatusTest CoverageDownloadsDependency Status

    中文英语

    我使用 Markdown 和wiki来管理api文档,我已经受了很多的痛苦。 它浪费了太多时间,而且非常无聊。 当你更改api时,应该修复 docuement。 测试和调试是非常重要的。 api文档的管理完全依赖于人们。 因此,docuement具有高质量是很难的。 同时,开发人员将花费更多的时间进行测试,这对项目的影响可能会。 更糟糕的是,它会影响我们的情绪,这对我来说 (

    所以我尽量解决这个问题。 当有遗嘱的时候有一种方法。 最后,我找到了 OpenAPI规范。 生态圈是完美的。 Swagger 包括许多工具链。 根据规范,Swagger UI 可以生成 docuement。 OpenAPI的数据类型和模型基于 json模式草案 4.

    我真心希望这个库能帮助那些遇到同样问题的人。 开心编码。

    BTW,PR &问题&星欢迎 ! : )

    特性
    • 内置swagger用户界面,易于查看和调试
    • 支持 openapi/swagger2.0 规范,带有yaml或者json文件
    • 更加友好和方便的api文档拆分解决方案
    • 插件系统。中间件加载器。表单验证器。响应处理程序。支持的错误处理程序
    • koa路由器继承,保持原有功能,功能和性能
    迁移

    如果你不是 1.x 用户,请直接跳过这里部分。 如果你是 1.x 用户并且希望升级到 2.0版,那么很抱歉你不会升级到 2.0版本。 请仔细阅读这里迁移文件,并按照操作手册进行升级。

    安装
    # required koa 2.x> npm install koa-oai-router --save
    正在启动

    下面将教你如何使用路由器构建具有良好组织结构和 api-explorer的web服务器。

    在这种情况下,它基本上涵盖了路由器的所有关键点,包括:

    • 配置路由器
    • 配置插件
    • 将插件装入路由器
    • 将路由器安装到应用程序
    • 编写api文档
    • 使用插件
    • api资源管理器

    我们的目标是:

    • 创建 REST API 服务器
    • 实现宠物查询api并返回找到的宠物的array
    • 实现宠物的创建api并返回宠物和 id
    • 生成api文档并享受api资源管理器

    开始了.

    创建网络服务器

    //./app.jsconstKoa=require('koa');constlogger=require('koa-logger');constbodyParser=require('koa-bodyparser');constRouter=require('koa-oai-router');constmiddleware=require('koa-oai-router-middleware');constapp=newKoa();// *configure router - load api doc from directory apiconstrouter=newRouter({
     apiDoc:'./api',
    });// *configure plugin - identify x-oai-middleware in the api file and load the appropriate middleware from controllers// *mount plugin to routerrouter.mount(middleware, './controllers');app.use(logger());app.use(bodyParser());// *mount router to appapp.use(router.routes());app.listen(3000);

    创建业务中间件

    创建业务中间件目录 controllers 并编写业务中间件。

    //./controllers/pets.jsconstdatabase= [];// Query pets in the database according to tags, and limit the query result according to the limit.asyncfunctionget(ctx, next) {
     const { tags='', limit =999 } =ctx.request.query;
     consttagsArray=tags.split(',');
     constdocs= [];
     database.forEach((item, idx) => {
     if (tagsArray.indexOf(item.tag) !==-1&&docs.length< limit) {
     item.id= idx +1;
     docs.push(item);
     }
     });
     ctx.response.body= docs;
    }// Create a pet store to the database.asyncfunctionpost(ctx, next) {
     constbody=ctx.request.body;
     database.push(body);
     ctx.response.body= {
     id:database.length,
     name:body.name,
     tag:body.tag,
     };
    }module.exports= {
     get,
     post,
    };

    创建api文档

    如果你对 OpenAPI 一无所知,请仔细阅读 OpenAPI。

    编写api基础信息

    你可以描述服务的基本信息,比如服务的版本。基本路径。传输协议。作者和权限许可证。

    #./api/api.yamlswagger: '2.0'info:
     version: 1.0.0title: Swagger Petstoredescription: >- A sample API that uses a petstore as an example to demonstrate features in the swagger-2.0 specificationtermsOfService: 'http://swagger.io/terms/'contact:
     name: Swagger API Teamlicense:
     name: MITbasePath: /apischemes:
     - httpconsumes:
     - application/jsonproduces:
     - application/json

    写入 paths 信息

    保存各个端点的相对路径。 将路径追加到 basePath,以便构造完整的URL。 请参考路径。

    #./api/paths/pets.yaml/pets:
     get:
     description: "Returns all pets from the system that the user has access to"operationId: "findPets"produces:
     - "application/json"tags:
     - petsx-oai-middleware:
     - file: petshandler: getparameters:
     - name: "tags"in: "query"description: "tags to filter by"required: falsetype: "array"items:
     type: "string"collectionFormat: "csv" - name: "limit"in: "query"description: "maximum number of results to return"required: falsetype: "integer"format: "int32"responses:
     "200":
     description: "pet response"schema:
     type: "array"items:
     $ref: "#/definitions/Pet"default:
     description: "unexpected error"schema:
     $ref: "#/definitions/ErrorModel"post:
     description: "Creates a new pet in the store. Duplicates are allowed"operationId: "addPet"produces:
     - "application/json"tags:
     - petsx-oai-middleware:
     - file: petshandler: postparameters:
     - name: "pet"in: "body"description: "Pet to add to the store"required: trueschema:
     $ref: "#/definitions/NewPet"responses:
     "200":
     description: "pet response"schema:
     $ref: "#/definitions/Pet"default:
     description: "unexpected error"schema:
     $ref: "#/definitions/ErrorModel"

    写入 definitions 信息

    定义对象以保存可以由操作使用和生成的数据类型。 这些数据类型可以是基元,数组或者模型。 请参考定义

    1.Define 接口错误响应数据模型 ErrorModel

    #./api/definitions/error.yamlErrorModel:
     type: "object"required:
     - "code" - "message"properties:
     code:
     type: "integer"format: "int32"message:
     type: "string"

    2.Define 查询成功响应数据模型 Pet,定义新的请求数据模型 NewPet

    #./api/definitions/pets.yamlPet:
     type: "object"allOf:
     - $ref: "#/definitions/NewPet" - required:
     - "id"properties:
     id:
     type: "integer"format: "int64"NewPet:
     type: "object"required:
     - "name"properties:
     name:
     type: "string"tag:
     type: "string"

    api浏览器

    启动WEB服务,测试接口并享受api资源管理器。

    > node app.js>> curl -X POST "http://localhost:3000/api/pets" -H "Content-Type: application/json" -d "{ "name": "luck", "tag": "dog"}"> {"id":1,"name":"luck","tag":"dog"}>> curl -X POST "http://localhost:3000/api/pets" -H "Content-Type: application/json" -d "{ "name": "lily", "tag": "cat"}"> {"id":2,"name":"lily","tag":"cat"}>> curl -X POST "http://localhost:3000/api/pets" -H "Content-Type: application/json" -d "{ "name": "mike", "tag": "dog"}"> {"id":3,"name":"mike","tag":"dog"}>> curl -X GET "http://localhost:3000/api/pets?tags=cat,dog&limit=2"> [{"name":"luck","tag":"dog","id":1},{"name":"lily","tag":"cat","id":2}]

    你可以看到,我们编写的所有业务中间件都被正常调用。 使用浏览器打开 http://localhost:3000/api-explorer,你现在可以享受api资源管理器。 Api Explorer

    文档生态系统 NAME 描述状态
    koa-oai-router-middleware中间件加载器正在开发
    koa-oai-router-correction表单修正正在开发
    koa-oai-router-parameters表单验证程序正在开发
    koa-oai-router-responses响应处理程序正在开发
    koa-oai-router-cache请求缓存规划
    koa-oai-router-rbac请求 rbac规划
    koa-oai-router-mongoMongoDB REST服务器规划
    计划
    • 支持 openapi/swagger3。0
    • 更多插件
    • 更多单元测试
    • 基准




    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备17041772号-2  |  如果智培  |  酷兔英语  |  帮酷