{"id":16843218,"url":"https://github.com/jbowes/oag","last_synced_at":"2025-03-17T05:31:58.668Z","repository":{"id":25932005,"uuid":"106920583","full_name":"jbowes/oag","owner":"jbowes","description":"Idiomatic Go (Golang) client package generation from OpenAPI documents","archived":false,"fork":false,"pushed_at":"2023-02-25T09:31:20.000Z","size":382,"stargazers_count":52,"open_issues_count":21,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-27T18:12:30.196Z","etag":null,"topics":["code-generation","code-generator","go","golang","openapi","openapi-client","rest","rest-api","swagger"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbowes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2017-10-14T10:58:37.000Z","updated_at":"2024-10-08T13:27:35.000Z","dependencies_parsed_at":"2024-06-19T00:12:09.293Z","dependency_job_id":"1b6fc5e2-08a9-4525-91b1-a4ad0a13c30d","html_url":"https://github.com/jbowes/oag","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbowes%2Foag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbowes%2Foag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbowes%2Foag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbowes%2Foag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbowes","download_url":"https://codeload.github.com/jbowes/oag/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243846976,"owners_count":20357294,"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":["code-generation","code-generator","go","golang","openapi","openapi-client","rest","rest-api","swagger"],"created_at":"2024-10-13T12:50:00.783Z","updated_at":"2025-03-17T05:31:58.272Z","avatar_url":"https://github.com/jbowes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\n  Attractive html formatting for rendering in github. sorry text editor\n  readers! Besides the header and section links, everything should be clean and\n  readable.\n--\u003e\n\u003ch1 align=\"center\"\u003eoag\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003ci\u003eIdiomatic \u003ca href=\"https://golang.org\"\u003eGo\u003c/a\u003e client package generation from \u003ca href=\"https://www.openapis.org/\"\u003eOpenAPI\u003c/a\u003e documents\u003c/i\u003e\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"Alpha Quality\" src=\"https://img.shields.io/badge/status-ALPHA-orange.svg\" \u003e\n  \u003ca href=\"https://travis-ci.org/jbowes/oag\"\u003e\u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/jbowes/oag.svg?branch=master\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/jbowes/oag/releases/latest\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/release/jbowes/oag.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"MIT license\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/jbowes/oag\"\u003e\u003cimg alt=\"codecov\" src=\"https://img.shields.io/codecov/c/github/jbowes/oag.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/jbowes/oag\"\u003e\u003cimg alt=\"Go Report Card\" src=\"https://goreportcard.com/badge/github.com/jbowes/oag\"\u003e\u003c/a\u003e\n\u003c/div\u003e\u003cbr /\u003e\u003cbr /\u003e\n\n\n## Introduction\nIntroduction | [Examples] | [Usage] | [Configuration] | [Contributing] | [License] \u003cbr /\u003e\u003cbr /\u003e\n\n🚧 ___Disclaimer___: _`oag` is alpha quality software. The API of generated code\nand configuration file format may change without warning between revisions._\n___Please check your generated code before use!___ 🚧\n\n`oag` generates idiomatic [Go] client packages from [OpenAPI] documents.\n[OpenAPI 2.0][openapi2] (née Swagger 2.0) is supported, with support for\n[OpenAPI 3.0.0][openapi3] coming [soon](https://github.com/jbowes/oag/issues/5).\n\n### Features\n\n- __Idiomatic Concise Code__: `oag` generates code modeled after some of [Go]'s\n  best REST API clients, like [GitHub] and [Stripe].\n- __Extensible__: Generated code is written to a single file. You are free to\n  add your own files to the package, adding behaviour to the generated types.\n- __Fast__: Code is generated in milliseconds.\n- __Commit Friendly__: Generated code is deterministic and stable. Multiple runs\n  produce the same output. Document additions and removals create clean diffs.\n- __Build Tool Friendly__: If the generated code has not changed, nothing is\n  written, and timestamps stay the same. A run of `oag` won't needlessly trigger\n  other targets in `make`.\n- __Single File Output__: All generated code is written to a single file.\n  Removals from an [OpenAPI] document won't result in orphaned generated files.\n\n\n## Examples\n[Introduction] | Examples | [Usage] | [Configuration] | [Contributing] | [License] \u003cbr /\u003e\u003cbr /\u003e\n\nThe minimal petstore OpenAPI 2.0 example (edited for brevity):\n\n```go\n// Client is an API client for all endpoints.\ntype Client struct {\n    Pets *PetsClient\n    // contains filtered or unexported fields\n}\n\n// New returns a new Client with the default configuration.\nfunc New() *Client {}\n\n// Pet is a data type for API communication.\ntype Pet struct {\n    ID   int     `json:\"id\"`\n    Name string  `json:\"name\"`\n    Tag  *string `json:\"tag\"` // Optional\n}\n\n// PetIter Iterates over a result set of Pets.\ntype PetIter struct {\n    // contains filtered or unexported fields\n}\n\n// Close closes the PetIter and releases any associated resources. After\n// Close, any calls to Current will return an error.\nfunc (i *PetIter) Close() {}\n\n// Current returns the current Pet, and an optional error. Once an error\n// has been returned, the PetIter is closed, or the end of iteration is\n// reached, subsequent calls to Current will return an error.\nfunc (i *PetIter) Current() (*Pet, error) {}\n\n// Next advances the PetIter and returns a boolean indicating if the end\n// has been reached. Next must be called before the first call to Current.\n// Calls to Current after Next returns false will return an error.\nfunc (i *PetIter) Next() bool {}\n\n// PetsClient provides access to the /pets APIs\ntype PetsClient endpoint\n\n// List corresponds to the GET /pets endpoint. Returns all pets from the\n// system that the user has access to\nfunc (c *PetsClient) List(ctx context.Context) *PetIter {}\n```\n\n[View the complete generated client code][petstore]\n\n## Usage\n[Introduction] | [Examples] | Usage | [Configuration] | [Contributing] | [License] \u003cbr /\u003e\u003cbr /\u003e\n\n#### Install `oag`\n\n``` bash\ngo get -u github.com/jbowes/oag\n```\n\n#### Initialize and edit your configuration file\n\n``` bash\n# In the directory under your $GOPATH where your package will live\noag init\n# Edit the created .oag.yaml file, following the comments\n```\n\n#### Generate and commit your code\n\n``` bash\noag\ngit add zz_oag_generated.go\ngit commit -m \"Add autogenerated API client\"\n```\n\n#### Implement the [error] interface for your error types\n\n`oag` can determine which types are used as errors, but it does not know how you\nwish to present them.\n\nCreate a new file in the same package that implements [error] for your type. For\nexample, if `zz_oag_generated.go` contained:\n\n```go\ntype APIError struct {\n\tID\tstring `json:\"id\"`\n\tMessage string `json:\"message\"`\n\tClass\tstring `json:\"class\"`\n}\n```\n\nWhere `ID` is some unique value generated per error, and `Class` is a group of\nerror types, you could put the following in an `error.go` file:\n\n```go\n// Error returns a string representation of this error\nfunc (a *APIError) Error() string {\n\treturn fmt.Sprintf(\"%s: %s (%s)\", a.ID, a.Message, a.Class)\n}\n```\n\n\n## Configuration\n[Introduction] | [Examples] | [Usage] | Configuration | [Contributing] | [License] \u003cbr /\u003e\u003cbr /\u003e\n\n`oag` keeps its configuration in a separate file rather than relying on OpenAPI\nvendor extensions. If you are not the original author of the OpenAPI document,\nyou don't need to carry patches to it to use `oag`.\n\nBy default, the file `.oag.yaml` is used for configuration. You may override\nthis with the `-c` flag.\n\n### Configuration Directives\n\n#### document\n\nRequired OpenAPI document to generate a client for.\n\n__Example:__\n```yaml\ndocument: ./openapi.yaml\n```\n\n#### package\n\nThe package path and optional name to use in the generated code.\n\n__Example:__\n```yaml\npackage:\n  path: github.com/jbowes/go-sample\n  name: sample\n```\n\n#### types\n\nOptional mapping of definitions to types.\n\n__Example:__\n```yaml\ntypes:\n  SomeDefinedType: github.com/org/package.TypeName\n```\n\n#### string_formats\n\nAn optional map of OpenAPI `format` values to Go types. Schema fields, array\nitems, and parameters that have these formats will be represented in the\ngenerated code with the provided type.\n\nAny types used here must implement the [TextMarshaler] interface.\n\n__Example:__\n```yaml\nstring_formats:\n  telephone: github.com/org/package.TelephoneNumber\n```\n\n#### output\n\nAn optional override for the default output file.\n\n__Example:__\n```yaml\noutput: zz_oag_generated_client_file.go\n```\n\n#### boilerplate\n\nA niche configuration directive, allowing you to disable parts of `oag`'s code\ngeneration, particularly for shipping generated code for multiple OpenAPI\ndocuments in the same package.\n\n__Example:__\n```yaml\nboilerplate:\n  base_url: disabled\n  backend: disabled\n  endpoint: disabled\n  client_prefix: PutThisBeforeTypeNames\n```\n\n\n## Contributing\n[Introduction] | [Examples] | [Usage] | [Configuration] | Contributing | [License] \u003cbr /\u003e\u003cbr /\u003e\n\nI would love your help!\n\n`oag` is still a work in progress. You can help by:\n\n- Trying `oag` against different [OpenAPI] documents, and [reporting bugs][bug]\n  when the generated code is broken, or [suggesting improvements][enhancement]\n  to the generated code.\n- Opening a pull request to resolve an [open issue][issues].\n- Adding a feature or enhancement of your own! If it might be big, please\n  [open an issue][enhancement] first so we can discuss it.\n- Improving this `README` or adding other documentation to `oag`.\n- Letting [me] know if you're using `oag`.\n\n\n## License\n[Introduction] | [Examples] | [Usage] | [Configuration] | [Contributing] | License \u003cbr /\u003e\u003cbr /\u003e\n\n[MIT](./LICENSE)\n\n```\nMIT License\n\nCopyright (c) 2017 James Bowes\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n\n\u003c!-- Section link definitions --\u003e\n[introduction]: #introduction\n[examples]: #examples\n[usage]: #usage\n[configuration]: #configuration\n[contributing]: #contributing\n[license]: #license\n\n\u003c!-- Other links --\u003e\n[go]: https://golang.org\n\n[error]: https://golang.org/pkg/builtin/#error\n[textmarshaler]: https://golang.org/pkg/encoding/#TextMarshaler\n\n[github]: https://godoc.org/github.com/google/go-github/github\n[stripe]: https://godoc.org/github.com/stripe/stripe-go\n\n[openapi]: https://www.openapis.org\n[openapi2]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md\n[openapi3]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md\n\n[issues]: ./issues\n[bug]: ./issues/new?labels=bug\n[enhancement]: ./issues/new?labels=enhancement\n\n[petstore]: ./_example/petstore/zz_oag_generated.go\n\n[me]: https://twitter.com/jrbowes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbowes%2Foag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbowes%2Foag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbowes%2Foag/lists"}