Skip to content

JennieJi/protobuf2swagger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

49 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

protobuf2swagger

Work in progress project for saving some life, update not garrenteed. Welcome for pull request :).

Main purpose is to convert protobuf v2 file to openapi v3 JSON schema with NodeJS, and merge with some custom open api configurations.
Then you may render it easily with SwaggerUI.

What is supported

  • customSchema in OAS v2 or v3 formats
  • convert service to paths
  • convert enum, enum to schemas in components/definitions, paths will reference to them
  • basic types mapping to JS type number, string, boolean ( long types will be mapped to string)
  • nested, repeated types

Install

npm i -g protobuf2swagger

Cli Usage

protobuf2swagger [config_file]

Argument Description
config_file Customize configuration file. Default to protobuf2swagger.config.js under current folder.

For options may check protobuf2swagger --help. (Nothing there yet, seriously.)

Config File

Example:

module.exports = {
  // ERQU
  files: ['test1.proto', 'test2.proto'],
  // Optional
  dist: 'apischema.json',
  // Optional
  formatServicePath: (path) => path.replace(/\./g, '/'),
  // Optional, will convert long to string by default
  long: 'number',
  // Optional
  // This will merge and overwrite the result parsed from protobuffer file.
  // `paths` will merge by path
  // `components` will merge by component except shcemas
  customSchema: {
    swagger: '2.0',
    paths: {
      '/api/test': {
        get: {
          responses: {
            200: {
              schema: {
                $ref: 'GetDataResponse', // Tell me the protobuf message name
              },
            },
          },
          params: [],
        },
      },
    },
    components: {
      securitySchemes: {
        cookieAuth: {
          type: 'apiKey',
          in: 'cookie',
          name: 'token',
        },
      },
    },
    security: [
      {
        cookieAuth: [],
      },
    ],
  },
  // Optional, you may use this hook to overwrite the original transform result.
  transform(type, result, args) {
    switch (type) {
      case 'field': {
        const [field, options] = args;
        console.log('message field:', field);
        console.log('options:', options);
        break;
      }
      case 'message': {
        const [message, options] = args;
        console.log('message:', messsage);
        console.log('options:', options);
        break;
      }
      case 'enum': {
        const [enum] = args;
        console.log('enum:', enum);
        break;
      }
      case 'service': {
        const [service, root, options] = args;
        console.log('service:', service);
        console.log('proto root:', root);
        console.log('options:', options);
      }
    }
    return result;
  },
};

Display with SwaggerUI

index.html (modified from swagger-ui-dist)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>API Document</title>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.2/swagger-ui.css"
    />
    <style>
      html {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after {
        box-sizing: inherit;
      }

      body {
        margin: 0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div id="swagger-ui"></div>

    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.2/swagger-ui-bundle.js"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.2/swagger-ui-standalone-preset.js"></script>
    <script>
      window.onload = function () {
        // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
          url: './apischema.json', // Path to the generated schema JSON file
          dom_id: '#swagger-ui',
          deepLinking: true,
          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
          layout: 'StandaloneLayout',
        });
        // End Swagger UI call region
        window.ui = ui;
      };
    </script>
  </body>
</html>

Serve with simple express server:

const express = require('express');
const app = express();

app.use(express.static(__dirname /* path to index.html */));
app.listen(3000);

console.info('Served at port 3000');

About

Convert protobuf v2 to swagger openapi v3 JSON

Resources

License

Stars

Watchers

Forks

Packages

No packages published