ARCHIVED - Use https://github.com/go-bridget/twirp-swagger-gen instead
NOTE: This is new and barely tested. If you find problems, please open an issue :)
Also Note: None of the clients or servers generated from swagger support protobuf. Only json.
A plugin for the awesome twirp - https://github.com/twitchtv/twirp
It is a protobuf generator that creates a swagger file for your twirp services.
This swagger file can then be used to generate documentation and clients for many many languages.
go get github.com/elliots/protoc-gen-twirp_swagger
then run as part of your usual protoc generation phase
protoc --go_out=. \
--twirp_out=. \
--twirp_swagger_out=. \
./test.protoYou can import the swagger file into a lot of other tools and services.
If you find any good ones, add an issue so we can list them here.
Proto file taken from the twirp example. All scripts/clients/docs are in example
./generate-swagger.sh will create service.swagger.json
{
"swagger": "2.0",
"info": {
"title": "service.proto",
"version": "version not set"
},
"schemes": [
"http",
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/twirp/twitch.twirp.example.Haberdasher/MakeHat": {
"post": {
"summary": "MakeHat produces a hat of mysterious, randomly-selected color!",
"operationId": "MakeHat",
"responses": {
"200": {
"description": "",
"schema": {
"$ref": "#/definitions/exampleHat"
}
}
},
"parameters": [
{
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/exampleSize"
}
}
],
"tags": [
"Haberdasher"
]
}
}
},
"definitions": {
"exampleHat": {
"type": "object",
"properties": {
"size": {
"type": "integer",
"format": "int32",
"description": "The size of a hat should always be in inches."
},
"color": {
"type": "string",
"description": "The color of a hat will never be 'invisible', but other than\nthat, anything is fair game."
},
"name": {
"type": "string",
"description": "The name of a hat is it's type. Like, 'bowler', or something."
}
},
"description": "A Hat is a piece of headwear made by a Haberdasher."
},
"exampleSize": {
"type": "object",
"properties": {
"inches": {
"type": "integer",
"format": "int32"
}
},
"description": "Size is passed when requesting a new hat to be made. It's always\nmeasured in inches."
}
}
}
./generate-clients.sh will create clients for C#, go, java, javascript, lua, python, and ruby (many more are available)
var Serviceproto = require('./javascript');
var devClient = new Serviceproto.ApiClient();
devClient.basePath = 'http://localhost:8080';
var api = new Serviceproto.HaberdasherApi(devClient);
var body = new Serviceproto.ExampleSize(); // {ExampleSize}
body.inches = 20;
var callback = function(error, data, response) {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ', data);
}
};
api.makeHat(body, callback);from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# create an instance of the API class
cfg = swagger_client.Configuration()
cfg.host="http://localhost:8080"
client = swagger_client.ApiClient(cfg)
api_instance = swagger_client.HaberdasherApi(client)
body = swagger_client.ExampleSize() # ExampleSize |
body.inches = 20
try:
# MakeHat produces a hat of mysterious, randomly-selected color!
api_response = api_instance.make_hat(body)
pprint(api_response)
except ApiException as e:
print("Exception when calling HaberdasherApi->make_hat: %s\n" % e)Note: You almost certainly want to use the twirp client, not the swagger one. No protobuf here.
package main
import (
"context"
"fmt"
"github.com/elliots/protoc-gen-twirp_swagger/example/clients/go"
)
func main() {
cfg := swagger.NewConfiguration()
cfg.BasePath = "http://localhost:8080"
client := swagger.NewAPIClient(cfg)
hat, resp, err := client.HaberdasherApi.MakeHat(context.Background(), swagger.ExampleSize{
Inches: 20,
})
if err != nil {
panic(err)
}
fmt.Printf("Got response code: %d hat: %v", resp.StatusCode, hat)
}./generate-documentation.sh
./generate-documentation.sh
Generates servers for rust and node.js.
See example/servers
Based on: https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-swagger (Like, 99.5% based on.)
Table of contents created by gh-md-toc
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent