thinkjs+swagger Editor

使用ThinkJS和Swagger Editor构建API文档站点

随着现代web应用的快速发展，越来越多的开发人员需要访问和理解API文档。正确编写API文档是整个应用程序的关键组成部分，因此，在构建API时应该考虑提供易于阅读和理解的文档。在这篇文章中，我们将介绍如何使用ThinkJS和Swagger Editor构建易于理解和阅读的API文档站点。

什么是API文档？

API文档是描述如何使用API的信息契约，对开发人员和API消费者非常重要，因为它们指导人们如何使用API、使用什么参数、以及可以获得什么样的反馈。API文档通常包括需要使用API的基本知识和技术细节，例如API端点和参数的定义。

什么是ThinkJS？

ThinkJS是一个非常流行的Node.js框架，它提供了一个快速开发web应用程序的核心基础设施。ThinkJS以其轻量级，易于学习，高性能和可扩展性受到开发人员的喜爱。使用ThinkJS来构建API文档相当容易。

什么是Swagger Editor？

Swagger Editor是一个通用的API文档编辑器，它允许你创建，编辑和调试OpenAPI规范文档。作为一个非常灵活的工具，Swagger Editor可以以多种不同的编程语言编写API文档，并允许使用者实时进行测试，为API设计和文档编写提供很多便利性。

如何使用ThinkJS和Swagger Editor构建API文档站点

我们先从安装ThinkJS和Swagger Editor开始，以下是一些简单的步骤和示例代码。

参考链接：官方文档

安装ThinkJS

npm install -g think-cli
think new project-name
cd project-name
npm install

安装Swagger Editor

npm install swagger-editor
swagger-editor

编写API文档

接下来，我们将在我们的项目目录下创建一个名为swagger.yaml的文件：

swagger: "2.0"
info:
  version: 1.0.0
  title: API Documentation
  description: API文档示例
host: localhost:8300
basePath: /
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /users:
    get:
      summary: 获取所有用户
      description: 获取所有用户列表
      responses:
        200:
          description: "success"
  /users/{id}:
    get:
      summary: 获取用户通过id
      description: 获取单个用户信息
      parameters:
        - in: path
          name: id
          required: true
          description: 用户唯一id
          type: integer
      responses:
        200:
          description: "success"
        404:
          description: "User not found"

将API文档与ThinkJS程序集成

让我们在应用程序中安装两个ThinkJS组件，分别是rest和swagger插件:

npm install think-swig --save
npm install think-rest --save
npm install think-swagger --save

现在我们需要在config文件夹下创建文件swagger.js：

module.exports = {
    port: 8300,
    prefix: '/api',
    doc: {
      swaggerDefinition: {
        info: {
          title: 'API Documentation',
          version: '1.0.0',
          description: 'API文档示例',
        },
        host: 'localhost:8300',
        basePath: '/api',
        produces: [
          "application/json"
        ],
        consumes: [
          "application/json"
        ],
        schemes: [
          "http"
        ],
      },
      apis: [
        // your files with api definition
        './router/*.js'
      ]
    }
  }

我们添加如下代码到文件router.js：

const Swagger = require('think-swagger')

module.exports = [
  {
    method: 'GET',
    path: '/users',
    handler: async (ctx) => {
      ctx.body = 'All users'
    }
  },
  new Swagger({
    swagger: {
      tags: [
        {
          name: 'Users Management',
          description: '用户管理',
        }
      ],
    },
    apis: [
      'lib/router/user.js'
    ],
    securityDefinitions: {
      ' JWT ': {
        'type': ' apiKey ',
        'in': ' header ',
        'name': ' Authorization '
      }
    }
  })
]

现在我们可以通过运行npm start来启动我们的程序，访问 http://localhost:8300/api-docs ，你将可以看到你的API的文档站点！

总结

在本文中，我们介绍了如何使用ThinkJS和Swagger Editor构建易于理解和阅读的API文档站点。通过结合两个工具和浏览器，可以获得快速、实时并且简单易懂的文档编写和API设计。相信了解本文章我们的读者应该可以快速切入到实战之中，完成更多高质API文档站的构建。