Hapi 的 Swagger 集成使用指南-JavaScript中文网-JavaScript教程资源分享门户

在开发前端应用程序时，API 的文档是非常重要的。Swagger 是一种用于描述和定义 RESTful API 的规范。它提供了一种自动化生成 API 文档的方式，使得开发者可以在不浪费时间的情况下构建准确的 API 文档。Hapi 是一个非常流行的 Node.js Web 框架，它提供了一种集成 Swagger 的方式。

在本文中，我们将介绍如何在 Hapi 中集成 Swagger，并提供一些使用指南和示例代码。让我们开始吧！

安装 Swagger 插件

首先，我们需要安装 hapi-swagger 插件。可以通过 npm 安装它：

npm install hapi-swagger

配置 Swagger 插件

安装完成后，我们需要将插件添加到 Hapi 应用程序中。以下是一个简单的示例：

// javascriptcn.com 代码示例
const Hapi = require('hapi');
const Inert = require('inert');
const Vision = require('vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');

const server = new Hapi.Server();

server.connection({
  host: 'localhost',
  port: 3000
});

const swaggerOptions = {
  info: {
    title: 'API Documentation',
    version: Pack.version,
  }
};

server.register([
  Inert,
  Vision,
  {
    register: HapiSwagger,
    options: swaggerOptions
  }
], (err) => {
  if (err) {
    console.log(`Error while loading plugins: ${err}`);
  }
});

server.start((err) => {
  if (err) {
    console.log(`Error while starting server: ${err}`);
  }

  console.log(`Server running at: ${server.info.uri}`);
});

在上面的代码中，我们首先引入了 hapi-swagger 插件和一些其他的 Hapi 插件。接下来，我们创建一个新的 Hapi 服务器并定义它的连接信息。然后，我们定义了 Swagger 的选项，包括 API 文档的标题和版本信息。最后，我们将 hapi-swagger 注册到 Hapi 应用程序中，并启动服务器。

编写 Swagger 规范

接下来，我们需要编写 Swagger 规范。Swagger 规范是一个 JSON 文档，它定义了 API 的路径、参数、响应等信息。以下是一个简单的示例：

// javascriptcn.com 代码示例
{
  "swagger": "2.0",
  "info": {
    "title": "API Documentation",
    "version": "1.0.0"
  },
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "paths": {
    "/users": {
      "get": {
        "description": "Get all users",
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}

在上面的代码中，我们定义了一个名为 /users 的 API 路径，它可以通过 GET 请求来获取所有的用户信息。我们还定义了响应类型为 JSON，并且在响应状态码为 200 时返回 "OK"。

集成 Swagger 规范

现在，我们需要将 Swagger 规范集成到 Hapi 应用程序中。以下是一个简单的示例：

// javascriptcn.com 代码示例
const Hapi = require('hapi');
const Inert = require('inert');
const Vision = require('vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');
const SwaggerSpec = require('./swagger.json');

const server = new Hapi.Server();

server.connection({
  host: 'localhost',
  port: 3000
});

const swaggerOptions = {
  info: {
    title: 'API Documentation',
    version: Pack.version,
  }
};

server.register([
  Inert,
  Vision,
  {
    register: HapiSwagger,
    options: swaggerOptions
  }
], (err) => {
  if (err) {
    console.log(`Error while loading plugins: ${err}`);
  }
});

server.route({
  method: 'GET',
  path: '/swagger.json',
  handler: function (request, reply) {
    reply(SwaggerSpec);
  },
  config: {
    description: 'Swagger JSON',
    tags: ['api'],
    plugins: {
      'hapi-swagger': {
        responses: {
          '200': {
            'description': 'Swagger specification'
          }
        }
      }
    }
  }
});

server.start((err) => {
  if (err) {
    console.log(`Error while starting server: ${err}`);
  }

  console.log(`Server running at: ${server.info.uri}`);
});

在上面的代码中，我们首先引入了 swagger.json 文件，它包含了我们编写的 Swagger 规范。接下来，我们将 swagger.json 文件作为路由添加到了 Hapi 应用程序中。最后，我们启动服务器。

使用 Swagger UI

现在，我们已经成功地将 Swagger 规范集成到了 Hapi 应用程序中。但是，我们还需要一种方式来查看和测试 API 文档。Swagger UI 是一个非常流行的工具，它可以自动生成 API 文档，并提供一个交互式界面来测试 API。

以下是如何在 Hapi 应用程序中使用 Swagger UI：

// javascriptcn.com 代码示例
const Hapi = require('hapi');
const Inert = require('inert');
const Vision = require('vision');
const HapiSwagger = require('hapi-swagger');
const Pack = require('./package');
const SwaggerSpec = require('./swagger.json');

const server = new Hapi.Server();

server.connection({
  host: 'localhost',
  port: 3000
});

const swaggerOptions = {
  info: {
    title: 'API Documentation',
    version: Pack.version,
  }
};

server.register([
  Inert,
  Vision,
  {
    register: HapiSwagger,
    options: swaggerOptions
  }
], (err) => {
  if (err) {
    console.log(`Error while loading plugins: ${err}`);
  }
});

server.route({
  method: 'GET',
  path: '/swagger.json',
  handler: function (request, reply) {
    reply(SwaggerSpec);
  },
  config: {
    description: 'Swagger JSON',
    tags: ['api'],
    plugins: {
      'hapi-swagger': {
        responses: {
          '200': {
            'description': 'Swagger specification'
          }
        }
      }
    }
  }
});

server.register(require('inert'), () => {
  server.route({
    method: 'GET',
    path: '/swaggerui/{param*}',
    handler: {
      directory: {
        path: 'node_modules/swagger-ui/dist',
        redirectToSlash: true,
        index: true
      }
    }
  });
});

server.start((err) => {
  if (err) {
    console.log(`Error while starting server: ${err}`);
  }

  console.log(`Server running at: ${server.info.uri}`);
});

在上面的代码中，我们首先引入了 inert 插件，它允许我们提供静态文件。接下来，我们将 Swagger UI 添加到了 Hapi 应用程序中，并将其映射到 /swaggerui 路径。最后，我们启动服务器。

现在，我们可以在浏览器中打开 http://localhost:3000/swaggerui 来查看和测试 API 文档。

总结

在本文中，我们介绍了如何在 Hapi 中集成 Swagger，并提供了一些使用指南和示例代码。通过使用 Swagger，我们可以自动化生成准确的 API 文档，并提供一个交互式界面来测试 API。希望这篇文章能够帮助你在前端开发中更好地使用 Hapi 和 Swagger。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/657edf86d2f5e1655d9c18a7