{"id":21658451,"url":"https://github.com/elliots/protoc-gen-twirp_swagger","last_synced_at":"2025-07-17T21:31:04.814Z","repository":{"id":53937927,"uuid":"118995099","full_name":"elliots/protoc-gen-twirp_swagger","owner":"elliots","description":"Swagger generator for twirp","archived":true,"fork":false,"pushed_at":"2021-08-01T01:42:31.000Z","size":722,"stargazers_count":62,"open_issues_count":10,"forks_count":15,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-17T12:45:54.571Z","etag":null,"topics":["grpc","protobuf","swagger","twirp"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elliots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-26T02:31:00.000Z","updated_at":"2024-04-13T20:56:17.000Z","dependencies_parsed_at":"2022-08-13T05:01:03.620Z","dependency_job_id":null,"html_url":"https://github.com/elliots/protoc-gen-twirp_swagger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliots%2Fprotoc-gen-twirp_swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliots%2Fprotoc-gen-twirp_swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliots%2Fprotoc-gen-twirp_swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elliots%2Fprotoc-gen-twirp_swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elliots","download_url":"https://codeload.github.com/elliots/protoc-gen-twirp_swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226304695,"owners_count":17603645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grpc","protobuf","swagger","twirp"],"created_at":"2024-11-25T09:29:16.803Z","updated_at":"2024-11-25T09:29:28.079Z","avatar_url":"https://github.com/elliots.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"## ARCHIVED - Use https://github.com/go-bridget/twirp-swagger-gen instead\n\n\n\n# Twirp Swagger Generator\n\nNOTE: This is new and barely tested. If you find problems, please open an issue :)\n\nAlso Note: None of the clients or servers generated from swagger support protobuf. Only json.\n\nTable of Contents\n=================\n\n  * [What is this?](#what-is-this)\n  * [Usage](#usage)\n  * [Other uses](#other-uses)\n  * [Full Example](#full-example)\n      * [Generating the swagger file](#generating-the-swagger-file)\n        * [Output](#output)\n      * [Generating Clients](#generating-clients)\n      * [Using the Clients](#using-the-clients)\n        * [JavaScript](#javascript)\n        * [Python](#python)\n        * [Go](#go)\n      * [Generating documentation](#generating-documentation)\n        * [Spectacle](#spectacle)\n        * [swagger-codegen (html2 language)](#swagger-codegen-html2-language)\n      * [Generating servers](#generating-servers)\n  * [Thanks](#thanks)\n\n## What is this?\n\nA plugin for the awesome twirp - https://github.com/twitchtv/twirp\n\nIt is a protobuf generator that creates a swagger file for your twirp services.\n\nThis swagger file can then be used to generate documentation and clients for many many languages.\n\n\n## Usage\n\n`go get github.com/elliots/protoc-gen-twirp_swagger`\n\nthen run as part of your usual protoc generation phase\n\n\n```bash\nprotoc --go_out=. \\\n       --twirp_out=. \\\n       --twirp_swagger_out=. \\\n       ./test.proto\n```\n\n## Other uses\n\nYou can import the swagger file into a lot of other tools and services.\n\nIf you find any good ones, add an issue so we can list them here.\n\n## Full Example\n\nProto file taken from the twirp example.\nAll scripts/clients/docs are in [example](example)\n\n### Generating the swagger file\n\n`./generate-swagger.sh` will create service.swagger.json\n\n\n#### Output\n```json\n\n{\n  \"swagger\": \"2.0\",\n  \"info\": {\n    \"title\": \"service.proto\",\n    \"version\": \"version not set\"\n  },\n  \"schemes\": [\n    \"http\",\n    \"https\"\n  ],\n  \"consumes\": [\n    \"application/json\"\n  ],\n  \"produces\": [\n    \"application/json\"\n  ],\n  \"paths\": {\n    \"/twirp/twitch.twirp.example.Haberdasher/MakeHat\": {\n      \"post\": {\n        \"summary\": \"MakeHat produces a hat of mysterious, randomly-selected color!\",\n        \"operationId\": \"MakeHat\",\n        \"responses\": {\n          \"200\": {\n            \"description\": \"\",\n            \"schema\": {\n              \"$ref\": \"#/definitions/exampleHat\"\n            }\n          }\n        },\n        \"parameters\": [\n          {\n            \"name\": \"body\",\n            \"in\": \"body\",\n            \"required\": true,\n            \"schema\": {\n              \"$ref\": \"#/definitions/exampleSize\"\n            }\n          }\n        ],\n        \"tags\": [\n          \"Haberdasher\"\n        ]\n      }\n    }\n  },\n  \"definitions\": {\n    \"exampleHat\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"size\": {\n          \"type\": \"integer\",\n          \"format\": \"int32\",\n          \"description\": \"The size of a hat should always be in inches.\"\n        },\n        \"color\": {\n          \"type\": \"string\",\n          \"description\": \"The color of a hat will never be 'invisible', but other than\\nthat, anything is fair game.\"\n        },\n        \"name\": {\n          \"type\": \"string\",\n          \"description\": \"The name of a hat is it's type. Like, 'bowler', or something.\"\n        }\n      },\n      \"description\": \"A Hat is a piece of headwear made by a Haberdasher.\"\n    },\n    \"exampleSize\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"inches\": {\n          \"type\": \"integer\",\n          \"format\": \"int32\"\n        }\n      },\n      \"description\": \"Size is passed when requesting a new hat to be made. It's always\\nmeasured in inches.\"\n    }\n  }\n}\n\n```\n\n### Generating Clients\n\n`./generate-clients.sh` will create clients for C#, go, java, javascript, lua, python, and ruby (many more are available)\n\n### Using the Clients\n\n#### JavaScript\n\n```javascript\n\nvar Serviceproto = require('./javascript');\n\nvar devClient = new Serviceproto.ApiClient();\ndevClient.basePath = 'http://localhost:8080';\n\nvar api = new Serviceproto.HaberdasherApi(devClient);\n\nvar body = new Serviceproto.ExampleSize(); // {ExampleSize} \nbody.inches = 20;\n\nvar callback = function(error, data, response) {\n  if (error) {\n    console.error(error);\n  } else {\n    console.log('API called successfully. Returned data: ', data);\n  }\n};\napi.makeHat(body, callback);\n\n```\n\n#### Python\n\n```python\n\nfrom __future__ import print_function\nimport time\nimport swagger_client\nfrom swagger_client.rest import ApiException\nfrom pprint import pprint\n# create an instance of the API class\ncfg = swagger_client.Configuration()\ncfg.host=\"http://localhost:8080\"\nclient = swagger_client.ApiClient(cfg)\napi_instance = swagger_client.HaberdasherApi(client)\nbody = swagger_client.ExampleSize() # ExampleSize | \nbody.inches = 20\n\ntry:\n    # MakeHat produces a hat of mysterious, randomly-selected color!\n    api_response = api_instance.make_hat(body)\n    pprint(api_response)\nexcept ApiException as e:\n    print(\"Exception when calling HaberdasherApi-\u003emake_hat: %s\\n\" % e)\n\n```\n\n\n#### Go\n\nNote: You almost certainly want to use the twirp client, not the swagger one. No protobuf here.\n\n```go\n\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/elliots/protoc-gen-twirp_swagger/example/clients/go\"\n)\n\nfunc main() {\n\tcfg := swagger.NewConfiguration()\n\tcfg.BasePath = \"http://localhost:8080\"\n\tclient := swagger.NewAPIClient(cfg)\n\n\that, resp, err := client.HaberdasherApi.MakeHat(context.Background(), swagger.ExampleSize{\n\t\tInches: 20,\n\t})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Printf(\"Got response code: %d hat: %v\", resp.StatusCode, hat)\n}\n\n```\n\n\n### Generating documentation\n\n`./generate-documentation.sh`\n\n#### Spectacle\n\n\u003cimg src=\"./example/spectacle.png\" style=\"max-width: 60%\"\u003e\n\n#### swagger-codegen (html2 language)\n\n\u003cimg src=\"./example/codegenhtml2.png\" style=\"max-width: 60%\"\u003e\n\n\n### Generating servers\n\n`./generate-documentation.sh`\n\nGenerates servers for rust and node.js.\n\nSee [example/servers](example/servers)\n\n## Thanks\n\nBased on: https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-swagger (Like, 99.5% based on.)\n\nTable of contents created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felliots%2Fprotoc-gen-twirp_swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felliots%2Fprotoc-gen-twirp_swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felliots%2Fprotoc-gen-twirp_swagger/lists"}