21xrx.com
2024-09-19 09:31:21 Thursday
登录
文章检索 我的文章 写文章
使用Node.js与Proto3和Swagger创建API
2023-07-05 02:06:43 深夜i     --     --
Node js Proto3 Swagger API 创建

Node.js是一个开放源代码、跨平台的JavaScript运行环境，用于构建高效、可扩展的应用程序。Node.js与谷歌开发的Proto3及其描述语言gRPC一起使用可以快速创建API。另外，Swagger也是一个流行的API工具，可以帮助开发人员创建、文档化和维护API。

在开始我们的教程之前，确保你已经熟悉了以下内容：

- Node.js的基础知识

- Proto3的基础知识

- Swagger的基础知识

接下来，我们将逐步介绍如何使用Node.js、Proto3和Swagger创建API。

1. 安装Node.js

在开始使用Node.js构建API之前，需要先安装Node.js。你可以在Node.js官网下载安装包，并按照指示安装即可。

2. 创建Proto3文件

接下来，我们需要创建一个Proto3的文件，定义消息格式和API方法。以下是一个简单的Proto3文件示例：



syntax = "proto3";


message Greeting


 string message = 1;


service GreetService {


 rpc Greet (Greeting) returns (Greeting) {}


}

在以上代码中，我们定义了一个消息Greeting，并在此消息中用一个字符串message传递一条问候语。接着，我们定义了一个服务GreetService，其中包含一个方法Greet，它接收一个Greeting消息，并返回一个Greeting消息作为响应。

3. 生成代码

接下来，我们需要使用Proto3编译器生成我们的代码。在终端中运行以下命令：



protoc --js_out=import_style=commonjs,binary:. greet.proto

在以上命令中，我们使用了protoc工具，指定生成的代码类型为JavaScript，并指定输出路径。这将生成一个JavaScript文件，其中包含我们定义的消息和服务的代码。

4. 实现服务

接下来，我们需要使用Node.js实现我们的服务。以下是一个简单的实现示例：



const grpc = require('grpc');


const protoLoader = require('@grpc/proto-loader');


const packageDefinition = protoLoader.loadSync('greet.proto');


const greet_proto = grpc.loadPackageDefinition(packageDefinition).GreetService;


const server = new grpc.Server();


function greet(call, callback) {


 callback(null, { message: `Hello, ${call.request.message}!` });


}


server.addService(greet_proto.service, { greet: greet });


server.bind('0.0.0.0:50051', grpc.ServerCredentials.createInsecure());


server.start();

在以上示例中，我们使用Node.js内置的grpc模块和@grpc/proto-loader模块加载我们生成的代码。接着，我们实现了一个greet方法来处理服务请求，并在服务器上添加了该服务。

最后，我们将服务器绑定到0.0.0.0:50051地址，并启动服务器。

5. 创建Swagger文档

Swagger可以帮助我们创建、文档化和维护API。使用以下内容创建一个swagger.yaml文件：



openapi: '3.0.0'


info:


 version: 1.0.0


 title: Greetings API


 description: Greet someone with a message


servers:


 - url: 'http://localhost:50051'


paths:


 /greet:


  post:


   summary: Send a greeting


   requestBody:


    description: Greeting message


    content:


     application/json:


      schema:


       $ref: '#/components/schemas/Greeting'


   responses:


    '200':


     description: OK


     content:


      application/json:


       schema:


        $ref: '#/components/schemas/Greeting'


components:


 schemas:


  Greeting:


   type: object


   properties:


    message:


     type: string

在以上代码中，我们定义了API的基本信息、服务器地址和一个API路径/greet。在Swagger文档中，我们定义了一个POST请求，并使用一个JSON消息体传递Greeting消息。

最后我们定义了Greeting对象的JSON模式，该模式包含一个message属性。

6. 生成服务器端Swagger绑定

最后，我们使用swagger-jsdoc生成服务器端Swagger绑定。在终端中运行以下命令：



npm install --save-dev swagger-jsdoc

接着，在你的服务器代码中添加以下内容：



const swaggerJSDoc = require('swagger-jsdoc');


const swaggerUi = require('swagger-ui-express');


const options = {


 definition: {


  openapi: '3.0.0',


  info:


  ,


  servers: [


   


   ,


  ],


 },


 apis: ['./greet.proto'],


};


const swaggerSpec = swaggerJSDoc(options);


app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

在以上示例中，我们首先加载swagger-jsdoc和swagger-ui-express模块。接着，我们定义了Swagger文档的基本信息，并指定了服务器地址。最后，我们通过swaggerJsdoc生成Swagger绑定，并将其与swagger-ui-express结合使用。

在以上步骤完成后，我们就已经创建了一个运行在Node.js上的Proto3和Swagger的API，你可以通过访问http://localhost:3000/api-docs查看API文档。

  
  

评论区

{{item['qq_nickname']}}
()
回复
回复