当前位置: 首页 > 软件库 > Web应用开发 > Web框架 >

koa-oai-router

授权协议 Readme
开发语言 JavaScript
所属分类 Web应用开发、 Web框架
软件类型 开源软件
地区 不详
投 递 者 施知
操作系统 跨平台
开源组织
适用人群 未知
 软件概览

Koa-OAI-Router

Build Status

中文 English

I have used markdown and wiki to manage api doc, from which I have suffered a lot. It wastes too much time and is very boring. The document should be repaired when you change the api. It's very unconvenient to test and debug. The management of api doc totally depends on people. As a result, it is hard to make document have high quality. Meanwhile, the developers will spend more time on testing, which may have a bad effect on project. What's worse, it will affect our mood, which is unbearable for me : (

So I try my best to solve this problem. When there is a will, there is a way. Finally, I find The OpenAPI Specification. And its ecological circle is perfect. Swagger includes lots of tool chain. According to the Specification, Swagger UI can produce the document. The data types and models of OpenAPI are based on the JSON-Schema Draft 4.

I truly hope that this library can help those who are in the same trouble. Happy coding.

BTW,PR & Issue & Star are welcome! : )



Features

  • Built-in Swagger-UI, easy to view and debug
  • Support OpenAPI/Swagger2.0 specification with yaml or json file
  • More friendly and convenient api doc splitting solution
  • Plugin system. Middleware loader, form validator, response handler, error handler supported as plugin
  • Inherit from Koa-Router, maintain the original function, features and performance

Migration

If you are not a 1.x user, please skip this section directly.If you are a 1.x user and want to upgrade to version 2.0, I'm sorry that you will not upgrade to version 2.0 easily. Please read this Migration carefully and follow the operation manual to upgrade.

Installation

# required koa 2.x
> npm install koa-oai-router --save

Getting Started

The following will teach you how to use the router to build a web server with a good organizational structure and api-explorer.

In this case, it basically covers all the key points of the router, including:

  • configure router
  • configure plugin
  • mount plugin to router
  • mount router to app
  • write api doc
  • use plugin
  • enjoy api-explorer

our target is:

  • to create a REST API Server
  • to implement a pets query api and return the array of pets found
  • to implement a creating api for pets and return the pet and id
  • to generate api documentation and enjoy api-explorer

Here we go.

Creating web server

// ./app.js

const Koa = require('koa');
const logger = require('koa-logger');
const bodyParser = require('koa-bodyparser');
const Router = require('koa-oai-router');
const middleware = require('koa-oai-router-middleware');

const app = new Koa();

// *configure router - load api doc from directory api
const router = new Router({
  apiDoc: './api',
});

// *configure plugin - identify x-oai-middleware in the api file and load the appropriate middleware from controllers
// *mount plugin to router
router.mount(middleware, './controllers');

app.use(logger());
app.use(bodyParser());
// *mount router to app
app.use(router.routes());

app.listen(3000);

Creating business middleware

Create business middleware directory controllers and write business middleware.

// ./controllers/pets.js

const database = [];

// Query pets in the database according to tags, and limit the query result according to the limit.
async function get(ctx, next) {
  const { tags = '', limit = 999 } = ctx.request.query;
  const tagsArray = tags.split(',');
  const docs = [];

  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.
async function post(ctx, next) {
  const body = ctx.request.body;

  database.push(body);

  ctx.response.body = {
    id: database.length,
    name: body.name,
    tag: body.tag,
  };
}

module.exports = {
  get,
  post,
};

Creating api doc

If you know nothing about OpenAPI, please read OpenAPI carefully.

Writing api base info

You can describe the basic information of the service, such as the version of the service, the basic path, transmission protocol, author and permission license.

# ./api/api.yaml

swagger: '2.0'
info:
  version: 1.0.0
  title: Swagger Petstore
  description: >-
    A sample API that uses a petstore as an example to demonstrate features in
    the swagger-2.0 specification
  termsOfService: 'http://swagger.io/terms/'
  contact:
    name: Swagger API Team
  license:
    name: MIT
basePath: /api
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json

Writing paths info

Holds the relative paths to the individual endpoints. The path is appended to the basePath in order to construct the full URL. Please refer to Paths.

# ./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:
      - pets
    x-oai-middleware:
      - file: pets
        handler: get
    parameters:
      - name: "tags"
        in: "query"
        description: "tags to filter by"
        required: false
        type: "array"
        items:
          type: "string"
        collectionFormat: "csv"
      - name: "limit"
        in: "query"
        description: "maximum number of results to return"
        required: false
        type: "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:
      - pets
    x-oai-middleware:
      - file: pets
        handler: post
    parameters:
      - name: "pet"
        in: "body"
        description: "Pet to add to the store"
        required: true
        schema:
          $ref: "#/definitions/NewPet"
    responses:
      "200":
        description: "pet response"
        schema:
          $ref: "#/definitions/Pet"
      default:
        description: "unexpected error"
        schema:
          $ref: "#/definitions/ErrorModel"

Writing definitions info

You can define an object to hold data types that can be consumed and produced by operations. These data types can be primitives, arrays or models. Please refer to Definitions.

1.Define interface error response data model ErrorModel.

# ./api/definitions/error.yaml

ErrorModel:
  type: "object"
  required:
    - "code"
    - "message"
  properties:
    code:
      type: "integer"
      format: "int32"
    message:
      type: "string"

2.Define query success response data model Pet, define new request data model NewPet.

# ./api/definitions/pets.yaml

Pet:
  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"

Enjoying api-explorer

Start WEB service, test interface and enjoy api-explorer.

> 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}]

As you can see, all of the business middleware we wrote has been called normally.Use a browser to open http://localhost:3000/api-explorer, and you can enjoy api-explorer now.

Documentation

Ecosystem

name description status
koa-oai-router-middleware middleware loader Done
koa-oai-router-correction form correction Done
koa-oai-router-parameters form validator Done
koa-oai-router-responses response handler Done
koa-oai-router-cache request cache Done
koa-oai-router-rbac request rbac Planning
koa-oai-router-controller-mongo MongoDB REST server Developing

Plan

  • Support OpenAPI/Swagger3.0
  • More plugins
  • More unit tests
  • Benchmark
 相关资料
  • Koa

    Koa art-template view render middleware. support all feature of art-template. Install npm install --save art-template npm install --save koa-art-template Example const Koa = require('koa'); const ren

  • koa

    koa是Express的下一代基于Node.js的web框架,目前有1.x和2.0两个版本。 历史 1. Express Express是第一代最流行的web框架,它对Node.js的http进行了封装,用起来如下: var express = require('express'); var app = express(); app.get('/', function (req, res) {

  • Koa

    Koa 是下一代的 Node.js 的 Web 框架。由 Express 团队设计。旨在提供一个更小型、更富有表现力、更可靠的 Web 应用和 API 的开发基础。 Koa可以通过生成器摆脱回调,极大地改进错误处理。Koa核心不绑定任何中间件,但提供了优雅的一组可以快速和愉悦地编写服务器应用的方法。 示例代码: var koa = require('koa');var app = koa();//

  • koa-react-router koa 2 middleware for React server side rendering and routing with react-router 5. Looking for React Router 3 support see v1 docs.Try React Router 5 though it's awesome! Usage To insta

  • Koa tree router Koa tree router is a high performance router for Koa. Features Fast. Up to 11 times faster than Koa-router. Benchmark Express-style routing using router.get, router.put, router.post, e

  • Koa - HelloWorld 以上便是全部了,我们重点来看示例,我们只注册一个中间件, Hello Worler Server: <?php $app = new Application(); // ... $app->υse(function(Context $ctx) { $ctx->status = 200; $ctx->body = "<h1>Hello Worl