Flesh out the examples, add more documentation

.gitignore

@@ -0,0 +1,6 @@
+
+example/clients/go/vendor/
+
+example/clients/javascript/node_modules/
+
+\.vscode/

README.md

@@ -1,15 +1,34 @@
-# protoc-gen-twirp_swagger
+# Twirp Swagger Generator
 
-NOTE: WORK IN PROGRESS. COMPLETELY UNTESTED.
+NOTE: This is new and barely tested. If you find problems, please open an issue :)
 
+Table of Contents
+=================
 
-## What this is
+  * [What is this?](#what-is-this)
+  * [Usage](#usage)
+  * [Other uses](#other-uses)
+  * [Full Example](#full-example)
+      * [Generating the swagger file](#generating-the-swagger-file)
+        * [Output](#output)
+      * [Generating Clients](#generating-clients)
+      * [Using the Clients](#using-the-clients)
+        * [JavaScript](#javascript)
+        * [Python](#python)
+        * [Go](#go)
+      * [Generating documentation](#generating-documentation)
+        * [Spectacle](#spectacle)
+        * [swagger-codegen (html2 language)](#swagger-codegen-html2-language)
+      * [Generating servers](#generating-servers)
+  * [Thanks](#thanks)
 
-A plugin for the awesome twirp - https://github.com/twitchtv/twirp.
+## What is this?
+
+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 clients for many many languages.
+This swagger file can then be used to generate documentation and clients for many many languages.
 
 
 ## Usage
@@ -26,26 +45,23 @@ protoc --go_out=. \
        ./test.proto
 ```
 
-Check out [./_example/generate.sh](./example/generate.sh)
-
+## Other uses
 
-## Generating Clients
+You can import the swagger file into a lot of other tools and services.
 
-See: [./_example/generate-clients.sh](./_example/generate-clients.sh) for example clients for javascript, java, python, ruby, lua, and c#. As well as generated html documentation.
+If you find any good ones, add an issue so we can list them here.
 
-Note that there are a thousand options to pass to the generators, I'm just running the default.
+## Full Example
 
+Proto file taken from the twirp example.
+All scripts/clients/docs are in [example](example)
 
-## Thanks
-
-Based on: https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-swagger
+### Generating the swagger file
 
-Like, 99.5% based on.
+`./generate-swagger.sh` will create service.swagger.json
 
 
-
-## Example output
-
+#### Output
 ```json
 
 {
@@ -126,4 +142,118 @@ Like, 99.5% based on.
   }
 }
 
-```
+```
+
+### Generating Clients
+
+`./generate-clients.sh` will create clients for C#, go, java, javascript, lua, python, and ruby (many more are available)
+
+### Using the Clients
+
+#### JavaScript
+
+```javascript
+
+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);
+
+```
+
+#### Python
+
+```python
+
+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)
+
+```
+
+
+#### Go
+
+Note: You almost certainly want to use the twirp client, not the swagger one. No protobuf here.
+
+```go
+
+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)
+}
+
+```
+
+
+### Generating documentation
+
+`./generate-documentation.sh`
+
+#### Spectacle
+
+<img src="./example/spectacle.png" style="max-width: 60%">
+
+#### swagger-codegen (html2 language)
+
+<img src="./example/codegenhtml2.png" style="max-width: 60%">
+
+
+### Generating servers
+
+It is possible to generate servers using swagger-codegen, but I haven't tried it myself.
+
+## Thanks
+
+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](https://github.com/ekalinin/github-markdown-toc)

_example/clients/csharp/IO.Swagger.sln → example/clients/csharp/IO.Swagger.sln

@@ -2,7 +2,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio 2012
 VisualStudioVersion = 12.0.0.0
 MinimumVisualStudioVersion = 10.0.0.1
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IO.Swagger", "src\IO.Swagger\IO.Swagger.csproj", "{D92EA715-85E8-4F20-A8FC-72146C5A4722}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IO.Swagger", "src\IO.Swagger\IO.Swagger.csproj", "{483B282F-B83E-4D40-B785-1537DB771139}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "IO.Swagger.Test", "src\IO.Swagger.Test\IO.Swagger.Test.csproj", "{19F1DEBC-DE5E-4517-8062-F000CD499087}"
 EndProject
@@ -12,10 +12,10 @@ Global
 		Release|Any CPU = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{D92EA715-85E8-4F20-A8FC-72146C5A4722}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{D92EA715-85E8-4F20-A8FC-72146C5A4722}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{D92EA715-85E8-4F20-A8FC-72146C5A4722}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{D92EA715-85E8-4F20-A8FC-72146C5A4722}.Release|Any CPU.Build.0 = Release|Any CPU
+		{483B282F-B83E-4D40-B785-1537DB771139}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{483B282F-B83E-4D40-B785-1537DB771139}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{483B282F-B83E-4D40-B785-1537DB771139}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{483B282F-B83E-4D40-B785-1537DB771139}.Release|Any CPU.Build.0 = Release|Any CPU
 		{19F1DEBC-DE5E-4517-8062-F000CD499087}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{19F1DEBC-DE5E-4517-8062-F000CD499087}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{19F1DEBC-DE5E-4517-8062-F000CD499087}.Release|Any CPU.ActiveCfg = Release|Any CPU

_example/clients/csharp/src/IO.Swagger.Test/IO.Swagger.Test.csproj → example/clients/csharp/src/IO.Swagger.Test/IO.Swagger.Test.csproj

@@ -81,7 +81,7 @@ OpenAPI spec version: version not set
   <Import Project="$(MsBuildToolsPath)\Microsoft.CSharp.targets" />
   <ItemGroup>
       <ProjectReference Include="..\IO.Swagger\IO.Swagger.csproj">
-          <Project>{D92EA715-85E8-4F20-A8FC-72146C5A4722}</Project>
+          <Project>{483B282F-B83E-4D40-B785-1537DB771139}</Project>
           <Name>IO.Swagger</Name>
       </ProjectReference>
   </ItemGroup>

_example/clients/csharp/src/IO.Swagger/IO.Swagger.csproj → example/clients/csharp/src/IO.Swagger/IO.Swagger.csproj

@@ -12,7 +12,7 @@ OpenAPI spec version: version not set
 
     <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
     <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
-    <ProjectGuid>{D92EA715-85E8-4F20-A8FC-72146C5A4722}</ProjectGuid>
+    <ProjectGuid>{483B282F-B83E-4D40-B785-1537DB771139}</ProjectGuid>
     <OutputType>Library</OutputType>
     <AppDesignerFolder>Properties</AppDesignerFolder>
     <RootNamespace>IO.Swagger</RootNamespace>

example/clients/go/.gitignore

@@ -0,0 +1,24 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test
+*.prof

example/clients/go/.travis.yml

@@ -0,0 +1,8 @@
+language: go
+
+install:
+  - go get -d -v .
+
+script:
+  - go build -v ./
+

example/clients/go/Gopkg.toml

@@ -0,0 +1,30 @@
+
+# Gopkg.toml example
+#
+# Refer to https://github.com/golang/dep/blob/master/docs/Gopkg.toml.md
+# for detailed Gopkg.toml documentation.
+#
+# required = ["github.com/user/thing/cmd/thing"]
+# ignored = ["github.com/user/project/pkgX", "bitbucket.org/user/project/pkgA/pkgY"]
+#
+# [[constraint]]
+#   name = "github.com/user/project"
+#   version = "1.0.0"
+#
+# [[constraint]]
+#   name = "github.com/user/project2"
+#   branch = "dev"
+#   source = "github.com/myfork/project2"
+#
+# [[override]]
+#  name = "github.com/x/y"
+#  version = "2.4.0"
+
+
+[[constraint]]
+  branch = "master"
+  name = "golang.org/x/net"
+
+[[constraint]]
+  branch = "master"
+  name = "golang.org/x/oauth2"

example/clients/go/README.md

@@ -0,0 +1,40 @@
+# Go API client for swagger
+
+No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
+
+## Overview
+This API client was generated by the [swagger-codegen](https://github.com/swagger-api/swagger-codegen) project.  By using the [swagger-spec](https://github.com/swagger-api/swagger-spec) from a remote server, you can easily generate an API client.
+
+- API version: version not set
+- Package version: 1.0.0
+- Build package: io.swagger.codegen.languages.GoClientCodegen
+
+## Installation
+Put the package under your project folder and add the following in import:
+```
+    "./swagger"
+```
+
+## Documentation for API Endpoints
+
+All URIs are relative to *http://localhost*
+
+Class | Method | HTTP request | Description
+------------ | ------------- | ------------- | -------------
+*HaberdasherApi* | [**MakeHat**](docs/HaberdasherApi.md#makehat) | **Post** /twirp/twitch.twirp.example.Haberdasher/MakeHat | MakeHat produces a hat of mysterious, randomly-selected color!
+
+
+## Documentation For Models
+
+ - [ExampleHat](docs/ExampleHat.md)
+ - [ExampleSize](docs/ExampleSize.md)
+
+
+## Documentation For Authorization
+ Endpoints do not require authorization.
+
+
+## Author
+
+
+