Swagger output for client and documentation generation.

[elliots]

I've started work on a generating swagger files for twirp services (almost 100% based on https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-swagger)

The clients would be JSON only (I think?), but still. Pretty useful to get working clients for java, .net, etc.. pretty quickly using https://github.com/swagger-api/swagger-codegen#overview

Would you prefer it as an external plugin (will you have a community repo or something?) or as part of the main package?

Example output from your sample proto..

{
  "swagger": "2.0",
  "info": {
    "title": "test.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."
    }
  }
}

[elliots]

I've checked something early in. Seems to be generating everything ok. Haven't actually used any of it yet :) https://github.com/elliots/protoc-gen-twirp_swagger

I checked in examples of generated clients for javascript, java, python, ruby, lua, and c# https://github.com/elliots/protoc-gen-twirp_swagger/tree/master/_example/clients

The html documentation generation is pretty nice too...

[spenczar]

Wow, this is amazing! Really, really excellent proof of concept.

I think this should be an external plugin, but it's one we should highlight. We're certainly going to have a list of community-written generators when we have a better documentation website. For now, we should throw a list on the README.

As soon as you feel confident enough that your stuff is stable enough to recommend others use it, please send a PR to add it to the README. Again, really cool stuff! 👍