{"id":49353568,"url":"https://github.com/oapi-codegen/oapi-codegen-exp","last_synced_at":"2026-04-27T11:30:34.999Z","repository":{"id":351425472,"uuid":"1210701228","full_name":"oapi-codegen/oapi-codegen-exp","owner":"oapi-codegen","description":"Experimental OpenAPI code generator for Go","archived":false,"fork":false,"pushed_at":"2026-04-15T01:34:50.000Z","size":13962,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T01:35:23.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oapi-codegen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["oapi-codegen","jamietanna"],"open_collective":"oapi-codegen"}},"created_at":"2026-04-14T17:11:41.000Z","updated_at":"2026-04-15T00:41:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oapi-codegen/oapi-codegen-exp","commit_stats":null,"previous_names":["oapi-codegen/oapi-codegen-exp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/oapi-codegen/oapi-codegen-exp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oapi-codegen%2Foapi-codegen-exp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oapi-codegen%2Foapi-codegen-exp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oapi-codegen%2Foapi-codegen-exp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oapi-codegen%2Foapi-codegen-exp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oapi-codegen","download_url":"https://codeload.github.com/oapi-codegen/oapi-codegen-exp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oapi-codegen%2Foapi-codegen-exp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32335295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-04-27T11:30:31.700Z","updated_at":"2026-04-27T11:30:34.991Z","avatar_url":"https://github.com/oapi-codegen.png","language":"Go","funding_links":["https://github.com/sponsors/oapi-codegen","https://github.com/sponsors/jamietanna","https://opencollective.com/oapi-codegen"],"categories":[],"sub_categories":[],"readme":"# `oapi-codegen` V3\n\nThis is an experimental prototype of a V3 version of oapi-codegen. The generated code and command line options are not yet stable. Use at your\nown risk.\n\n## What is new in Version 3\nThis directory contains an experimental version of oapi-codegen's future V3 version, which is based on [libopenapi](https://github.com/pb33f/libopenapi),\ninstead of the prior [kin-openapi](https://github.com/getkin/kin-openapi). This change necessitated a nearly complete rewrite, but we strive to be as\ncompatible as possible.\n\nWhat is working:\n  - All model, client and server generation as in earlier versions.\n  - We have added Webhook and Callback support, please see `./examples`, which contains the ubiquitous OpenAPI pet shop implemented in all supported servers\n    and examples of webhooks and callbacks implemented on top of the `http.ServeMux` server, with no additional imports.\n  - Echo V5 support has been added (Go 1.25 required)\n  - The `runtime` has changed a lot. By default, we generate all the needed runtime\n    functions into your generated code. You can, optionally, generate your own runtime\n    package locally, to avoid duplication between multiple openapi specifications. This\n    was done because the version pinning between runtime and the codegen was exceedingly\n    annoying, so now, the runtime is embedded into the generator itself, and there is\n    no versioning issue.\n  \nWhat is missing:\n  - Middleware, this is for someone else to solve.\n  - Good documentation. You'll have to read over the config file code to see how\n    to configure.\n\n## Differences in V3\n\nV3 is a brand new implementation, and may (will) contain new bugs, but also strives to fix many current, existing bugs. We've run quite a few\nconformance tests against specifications in old Issues, and we're looking pretty good! Please try this out, and if it failes in some way, please\nfile Issues.\n\n### Normalized extension names\n\nV3 normalizes all extension names under the `x-oapi-codegen-` prefix. The old names are still accepted for backwards compatibility.\n\n| V2 | This version                           | Scope | Purpose |\n|---|----------------------------------------|---|---|\n| `x-go-type` + `x-go-type-import` | `x-oapi-codegen-type-override`         | Schema, Property | Use an external Go type instead of generating one. V3 combines type and import into a single value: `\"TypeName;import/path\"`. |\n| `x-go-name` | `x-oapi-codegen-name-override`         | Property | Override the generated Go field name. |\n| `x-go-type-name` | `x-oapi-codegen-type-name-override`    | Schema | Override the generated Go type name. |\n| `x-go-type-skip-optional-pointer` | `x-oapi-codegen-skip-optional-pointer` | Property | Don't wrap optional fields in a pointer. |\n| `x-go-json-ignore` | `x-oapi-codegen-json-ignore`           | Property | Exclude the field from JSON (`json:\"-\"`). |\n| `x-omitempty` | `x-oapi-codegen-omitempty`             | Property | Explicitly control the `omitempty` JSON tag. |\n| `x-omitzero` | `x-oapi-codegen-omitzero`              | Property | Add `omitzero` to the JSON tag (Go 1.24+ `encoding/json/v2`). |\n| `x-enum-varnames` / `x-enumNames` | `x-oapi-codegen-enum-varnames`         | Schema (enum) | Override generated enum constant names. |\n| `x-deprecated-reason` | `x-oapi-codegen-deprecated-reason`     | Schema, Operation | Provide a deprecation reason for documentation. |\n| `x-order` | `x-oapi-codegen-order`                 | Property | Control field ordering in generated structs. |\n\n### OpenAPI V3.1 Feature Support\n\nThanks to [libopenapi](https://github.com/pb33f/libopenapi), we are able to parse OpenAPI 3.1 and 3.2 specifications. They are functionally similar, you can\nread the differences between `nullable` fields yourself, but they add some new functionality, namely `webhooks` and `callbacks`. We support all of them in\nthis prototype. `callbacks` and `webhooks` are basically the inverse of `paths`. Webhooks contain no URL element in their definition, so we can't register handlers\nfor you in your http router of choice, you have to do that yourself. Callbacks support complex request URL's which may reference the original request. This is\nsomething you need to pull out of the request body, and doing it generically is difficult, so we punt this problem, for now, to our users.\n\nPlease see the [webhook example](examples/webhook/). It creates a little server that pretends to be a door badge reader, and it generates an event stream\nabout people coming and going. Any number of clients may subscribe to this event. See the [doc.go](examples/webhook/doc.go) for usage examples.\n\nThe [callback example](examples/callback), creates a little server that pretends to plant trees. Each tree planting request contains a callback to be notified\nwhen tree planting is complete. We invoke those in a random order via delays, and the client prints out callbacks as they happen. Please see [doc.go](examples/callback/doc.go) for usage.\n\n#### Enum via `oneOf` + `const`\n\nOpenAPI 3.1 lets you express a named enum with per-value documentation by putting each variant in a `oneOf` branch with `const` and `title`:\n\n```yaml\nSeverity:\n  type: integer\n  oneOf:\n    - title: HIGH\n      const: 2\n      description: An urgent problem\n    - title: MEDIUM\n      const: 1\n    - title: LOW\n      const: 0\n      description: Can wait forever\n```\n\nV3 detects this idiom and emits a regular Go enum (`type Severity int` with `HIGH`, `MEDIUM`, `LOW` constants) — with the `description` rendered as a per-value doc comment — instead of a `oneOf` union. All branches must carry both `const` and `title`, and the outer schema must declare a scalar `type` (`string` or `integer`); otherwise the schema falls through to the standard union generator. Set `generation.skip-enum-via-oneof: true` to disable detection.\n\n### Flexible Configuration\n\noapi-codegen V3 tries to make no assumptions about which initialisms, struct tags, or name mangling that is correct for you. A very [flexible configuration file](Configuration.md) allows you to override anything.\n\n\n### No runtime dependency\n\nV2 generated code relied on `github.com/oapi-codegen/runtime` for parameter binding and styling. This was a complaint from lots of people due to various\naudit requirements. V3 embeds all necessary helper functions and helper types into the spec. There are no longer generic, parameterized functions that\nhandle arbitrary parameters, but rather very specific functions for each kind of parameter, and we call the correct little helper versus a generic\nruntime helper.\n\nWe still use the code generator to produce a pre-generated `runtime` package, which you are\nwelcome to use. It will always be consistent with the code generated with the corresponding\noapi-codegen. If you have lots of OpenAPI specs locally, you can also generate the runtime\npackage, as we do, in your own code to avoid bloat.\n\n### Models now support default values configured in the spec\n\nEvery model which we generate supports an `ApplyDefaults()` function. It recursively applies defaults on\nany unset optional fields. There's a little caveat here, in that some types are external references, so\nwe call `ApplyDefaults()` on them via reflection. This might call an `ApplyDefaults()` which is completely\nunrelated to what we're doing. Please let me know if this feature is causing trouble.\n\n## Installation\n\nGo 1.25 is required, install like so:\n\n    go get -tool github.com/oapi-codegen/oapi-codegen-exp/cmd/oapi-codegen@latest\n\nYou can then run the code generator\n\n    //go:generate go run github.com/oapi-codegen/oapi-codegen-exp/cmd/oapi-codegen\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foapi-codegen%2Foapi-codegen-exp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foapi-codegen%2Foapi-codegen-exp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foapi-codegen%2Foapi-codegen-exp/lists"}