preface

When I first looked at the open source Koa-Swagger-decorator project, I was surprised to see that online Swagger debugging is much easier than manual Postman debugging. So I thought about writing a complete project for myself and everyone to learn from.

Start with your own code: Koa-Swagger

introduce

This is a scaffolding based on Koa2 adding Swagger

Includes direct operations on the database by the corresponding Sequelize

And JWT certification

About the swagger

The koa-Swagger-decorator is used here

Features out of the box, support online debugging, RESTful API interface documentation is clear

But at the same time, it is very invasive, and the secondary development is very inconvenient. The schema is not reusable, so it is only suitable for small projects. (But if you’re a beginner, it’s even better for you!)

This project is designed to automatically generate interface documentation for the outside world by adding decorators to the Controller. Here’s an example:

Above the getTodoList method, we introduce decorators that describe swagger’s routing address, description, request parameters, etc

// list.js

import ListModel from 'models/list'
import { request, summary, description, query, path, body, tags } from 'koa-swagger-decorator'

const tag = tags(['list'])


const getListSchema = {
  keyword: { type: 'string'.required: true },
  status: { type: 'number'.required: true}}export default class ListController {
  @request('get'.'/list/list')
  @summary('Return a list')
  @description('example of api')
  @tag
  @query(getListSchema)
  static async getTodoList(ctx) {
    const data = ctx.request.query
    if (data) {
      const todoList = await ListModel.getTodoList(data.keyword, data.status)
      ctx.body = {
        code: 1.bean: {
          totalCount: todoList.totalCount,
          list: todoList.items,
        },
        message: 'success'}}else {
      ctx.body = {
        code: -1.message: 'Parameter error'}}}}Copy the code

And corresponding generated interfaces are as follows:

How to use

About Sequelize and databases

ORM Sequelize is used for relational databases

Multiple databases are supported. You need to modify the database connection Settings in config.js, for example, db_type: mysql Mariadb sqLite postgres MSSQL

NPM install mysql, NPM install postgres, etc…

Once the database is configured, it will automatically create the corresponding model for the database

Began to run

NPM install NPM run dev then open: http://localhost:3000/swagger-html you can see the familiar kind swagger pageCopy the code

Login and Authorization

The JWT approach is used here and token must be used. Path: [/^/user/login/, /^/user/register/, /^/swagger/, /^/public/]

The first step is to initialize the data using the /public/initData interface. At this point, the database generates the data of the logged-in user and the list

Step 2 Then returns the token in the registration interface /user/register or login interface /user/login request

The third step finally opens the Authorize token button, remembering that the front Bearer is then click Authorize.

Finally, after authorization, you can add, delete, and check the list

conclusion

This is the first time in nuggets published articles, if there is something wrong welcome to point out and discuss. If you are interested, you can continue to see the source code