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.
- customSchema in OAS v2 or v3 formats
- convert service to paths
- convert enum, message 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
npm i -g protobuf2swagger
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.)
Example:
module.exports = {
// Required
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
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: [],
},
],
},
};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');