Skip to content
This repository has been archived by the owner. It is now read-only.
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

ARCHIVED - Use instead

Twirp Swagger Generator

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.

Table of Contents

What is this?

A plugin for the awesome 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

then run as part of your usual protoc generation phase

protoc --go_out=. \
       --twirp_out=. \
       --twirp_swagger_out=. \

Other uses

You 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.

Full Example

Proto file taken from the twirp example. All scripts/clients/docs are in example

Generating the swagger file

./ will create service.swagger.json


  "swagger": "2.0",
  "info": {
    "title": "service.proto",
    "version": "version not set"
  "schemes": [
  "consumes": [
  "produces": [
  "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": [
  "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."

Generating Clients

./ will create clients for C#, go, java, javascript, lua, python, and ruby (many more are available)

Using the Clients


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) {
  } else {
    console.log('API called successfully. Returned data: ', data);
api.makeHat(body, callback);


from __future__ import print_function
import time
import swagger_client
from import ApiException
from pprint import pprint
# create an instance of the API class
cfg = swagger_client.Configuration()"http://localhost:8080"
client = swagger_client.ApiClient(cfg)
api_instance = swagger_client.HaberdasherApi(client)
body = swagger_client.ExampleSize() # ExampleSize | 
body.inches = 20

    # MakeHat produces a hat of mysterious, randomly-selected color!
    api_response = api_instance.make_hat(body)
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 (


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 {

	fmt.Printf("Got response code: %d hat: %v", resp.StatusCode, hat)

Generating documentation



swagger-codegen (html2 language)

Generating servers


Generates servers for rust and node.js.

See example/servers


Based on: (Like, 99.5% based on.)

Table of contents created by gh-md-toc