{"id":22144792,"url":"https://github.com/gas-buddy/swagger-csharp-client","last_synced_at":"2026-05-15T08:33:59.112Z","repository":{"id":74524618,"uuid":"76868728","full_name":"gas-buddy/swagger-csharp-client","owner":"gas-buddy","description":"A tool that generates a c# client from the Swagger specification from a GB api or service repo.","archived":false,"fork":false,"pushed_at":"2019-04-10T14:31:01.000Z","size":76,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-01-29T17:23:54.782Z","etag":null,"topics":["api","appveyor","client","csharp","nuget","swagger"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gas-buddy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-19T14:25:48.000Z","updated_at":"2019-04-10T14:31:00.000Z","dependencies_parsed_at":"2023-02-23T21:15:42.591Z","dependency_job_id":null,"html_url":"https://github.com/gas-buddy/swagger-csharp-client","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gas-buddy%2Fswagger-csharp-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gas-buddy%2Fswagger-csharp-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gas-buddy%2Fswagger-csharp-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gas-buddy%2Fswagger-csharp-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gas-buddy","download_url":"https://codeload.github.com/gas-buddy/swagger-csharp-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245267567,"owners_count":20587459,"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":["api","appveyor","client","csharp","nuget","swagger"],"created_at":"2024-12-01T22:32:52.529Z","updated_at":"2025-10-17T01:35:12.507Z","avatar_url":"https://github.com/gas-buddy.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# swagger-csharp-client\n\nA tool that generates a c# client from the Swagger specification found in a GB api or service repo.\n\n## Why Do We Need This?\n\n1. GasBuddy api and service Swagger specifications are broken down into multiple files (e.g. see [poi-api](https://github.com/gas-buddy/poi-api/tree/master/api)).  Existing tools for generating clients from Swagger specifications require a single file.  We deal with this by using [swagger-ref-resolver](https://github.com/gas-buddy/swagger-ref-resolver) to collate the Swagger specification prior to generating the client.\n\n2. We have chosen [swagger-codegen](https://github.com/swagger-api/swagger-codegen) as the c# client generator.  This tool is great, but we need to use a custom `swagger-codegen` template for the following reasons:\n\n    * The default c# template \"bakes\" the api host into the generated client code, but we want the api host to be specified in the client's\n    configuration file.\n    * We've changed the c# template to include the authorization token in the client's configuration file.\n    * There is bug in the default c# template that generates compiler errors in some cases when generating enumerations.\n\n# Setup\n\n## Prerequisites\n\nThis tool requires `maven`, which can be downloaded here: http://maven.apache.org/download.cgi\n\n1. Download the binary installation file\n2. Extract the binary file to the folder you want to run maven from\n3. Add the `bin` directory of the created directory apache-maven-3.3.9 to the `PATH` environment variable\n4. Run the following to check for `JAVE_HOME` environment variable\n\n```\necho %JAVA_HOME%\n```\n\n5. If the previous returns blank you need to create a JAVA_HOME environment variable to `C:\\Program Files\\Java\\jdk1.7.0_51` on windows or `/Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/Contents/Home` on Mac OS\n6. To confirm maven is working run the following in a new shell:\n\n```\nmvn -v\n```\n\nThe result should look similar to\n\n```\nApache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T04:57:37-07:00)\nMaven home: /opt/apache-maven-3.3.3\nJava version: 1.8.0_45, vendor: Oracle Corporation\nJava home: /Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/Contents/Home/jre\nDefault locale: en_US, platform encoding: UTF-8\nOS name: \"mac os x\", version: \"10.8.5\", arch: \"x86_64\", family: \"mac\"\n```\n\n## Clone and Install\n\n```\ngit clone git@github.com:gas-buddy/swagger-csharp-client.git\ncd swagger-csharp-client\nnpm install\n```\n\n# Generating an API Client\n\n## Make sure you have nuget and msbuild.exe\n\n* Try the command `nuget help`. If the command is not found, then you need to download nuget-cli from https://dist.nuget.org/index.html (Use the Windows Command line version). Put the installed nuget.exe file into your desired folder and add that folder to your PATH\n\n* Also add the MSBuild bin folder to your path, e.g. `C:\\Program Files (x86)\\MSBuild\\14.0\\Bin`\n\n\n## API Client With `nuget` Package\n\nIf you want to generate a client to be available on nuget(which you probably do), or update an existing client nuget package, then run the following:\n\n```\nnpm run generate-client [api-repo-name] [api-key]\n```\n\nThe api-key is the nuget api-key found on app-veyour. It is available in 1Password under the entry `AppVeyour Nuget ApiKey`\nOnce the process has finished running the client will be avaialble as a nuget package. After installing it you will be required to add the following app.config setting to your consumer project for the client to work.\n\n```\n\u003cadd key=\"[nuget-package-name-in-pascal-case].Host\" value=\"[service-url]\" /\u003e\n\u003cadd key=\"[nuget-package-name-in-pascal-case].Key\" value=\"[service-auth-key]\" /\u003e\n```\n\n## API Client Without `nuget` Package\n\nIf you just want to generate the code for a client in a local folder then run the following instead:\n```\nnpm run generate-client:folder [api-repo-name]\n```\n\nNote that the first time you run `generate-client` it will take several minutes to run as it needs to clone and build `swagger-codegen`.\n\n## Using Docker\nIf you don't want to install java or maven.  Simply run `run-gb-service` in order to go into an interactive shell to generate the .net client.  Once you are in the container run `npm install`.\n\n## Generating code from a swagger spec\nIn order to generate the code from a swagger spec, you can `npm run generate-from-spec arg1 arg2 arg3`. Where \n* arg1 is the path to the Swagger Doc\n* arg2 is the output directory and the nuget package id\n* arg3 is the name of the package\nExample:\n```\nnpm run generate-from-spec identity-serv-spec.json identity-serv-client IdentityServClient\n```\n\n## Example steps: Updating PoiApiClient\n1. Open two command prompts. cd into swagger-csharp-client in both\n2. Window 1: clone poi-api repo, cd into it, and `git checkout c-sharp-client`\n3. Window 1 again: `git checkout -b c-sharp-client-rpm-v2.0.0`\n4. Find the spec file that you want to generate from. This might come from an npm install, or if you have it locally just put it in the swagger-csharp-client project folder for now (e.g. poi-api-spec.json)\n5. Window 2: `run-gb-service`. This puts you in the container\n6. Window 2 (in container): `npm run generate-from-spec poi-api-spec.json poi-api PoiApiClient`\n7. Window 1: Verify that the generation was successful (`git status`)\n8. In the nested poi-api folder (Window 1), update the version in appveyor.yml\n9. In the case of poi-api, we need to update src/PoiApiClient/PoiApiApiClient.nuspec, changing the id from poi-api to poi-api-client. You may or may not need to do this, depending on the name of the project in appveyor\n10. Window 1: Commit and push the changes\n\n## Workflow for updating repo\nIt's a bit difficult to get git working in the container with ssh. So for the time being here is a workflow.\n\n1. Outside the container, but inside this project run `git clone {repoName}`\n2. Inside the container, run `npm run generate-from-spec {path_to_swagger_doc} {directory_of_repo} {package_name}`\n3. Outside the container, add the files, do a PR or a force push or whatever you like.\n\n## Appveyor integration\nThis repo will create an Appveyor.yml file that will get appveyor to build from the c-sharp-client branch.  You will need to add your project to Appveyor an initially set it to look at the c-sharp-client branch.    \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgas-buddy%2Fswagger-csharp-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgas-buddy%2Fswagger-csharp-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgas-buddy%2Fswagger-csharp-client/lists"}