{"id":24083287,"url":"https://github.com/mitranim/oas","last_synced_at":"2026-05-15T21:03:10.711Z","repository":{"id":57639388,"uuid":"432124901","full_name":"mitranim/oas","owner":"mitranim","description":"OpenAPI specs for your Go server, generated at server runtime using reflection. No CLI, no code generation, and no HTTP \"helpers\" 🤮.","archived":false,"fork":false,"pushed_at":"2023-07-27T14:10:46.000Z","size":28,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-20T15:56:57.319Z","etag":null,"topics":["go","golang","openapi","swagger"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/mitranim/oas","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mitranim.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,"zenodo":null}},"created_at":"2021-11-26T09:37:42.000Z","updated_at":"2023-08-01T09:08:35.000Z","dependencies_parsed_at":"2025-07-28T23:31:57.132Z","dependency_job_id":"d5aec865-40aa-4529-bafb-c03344fa9170","html_url":"https://github.com/mitranim/oas","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mitranim/oas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitranim%2Foas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitranim%2Foas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitranim%2Foas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitranim%2Foas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mitranim","download_url":"https://codeload.github.com/mitranim/oas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mitranim%2Foas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33080371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["go","golang","openapi","swagger"],"created_at":"2025-01-09T23:56:17.473Z","updated_at":"2026-05-15T21:03:10.680Z","avatar_url":"https://github.com/mitranim.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Overview\n\n\"oas\" is short for \"**O**pen**A**PI **S**pec\". Go package that generates JSON-schemas and OpenAPI docs from Go types and structures, at runtime.\n\n**Non**-features:\n\n  * No CLI.\n  * No code parsing.\n  * No code generation.\n  * No magic comments.\n  * No slowness.\n  * No dependencies.\n  * Nothing added to your HTTP stack.\n\nFeatures:\n\n  * Generates JSON schema definitions from Go types and structures.\n  * Provides struct types describing OpenAPI 3.1.\n  * Uses reflection to make OAS schemas from your types and structures.\n    * No more maintaining type definitions by hand in separate files.\n    * The source of truth is **your Go types**. Not some external YAML.\n    * Examines _actual_ encoding behavior of your types, at runtime, to determine formats and nullability.\n    * Supports references and cyclic types.\n  * Uses Go structs to describe what can't be reflected (routes, descriptions, etc).\n    * Structured, statically-typed format.\n    * Not an ad-hoc data format in breakage-prone comments.\n    * Not some external YAML.\n  * The docs are Go structures. You can do anything with them:\n    * Inspect and modify in Go.\n    * Encode as JSON or YAML.\n    * Write to disk or stdout at build time.\n    * Serve to clients at runtime.\n    * Visualize using an external tool.\n  * Tiny and dependency-free.\n\nSee [limitations](#limitations) below.\n\nAPI docs: https://pkg.go.dev/github.com/mitranim/oas\n\n## Why\n\n* No external CLI. Just a library.\n  * Automatically downloaded by Go.\n  * Automatically versioned via `go.mod`.\n  * No manual CLI installation.\n  * No manual CLI versioning.\n* No Go code generation.\n  * No `make generate` when pulling or switching branches.\n  * No waiting 1 minute for that stupidly slow generator.\n  * No manual remapping from crappy generated types to the types you **actually** want to use.\n  * No crappy 3rd party \"middleware\" in your HTTP stack.\n* No forced generation of OAS files. It's entirely optional.\n  * No manual reruns of a generate command.\n  * No bloating your commits and Git diffs with generated JSON/YAML.\n  * Can generate and serve OAS purely at runtime.\n* No figuring out how to deal with built artifacts.\n  * If you want built artifacts, it's an option. _Your Go app_ is a CLI tool. Add a command to encode its OAS as JSON, and run that at build time.\n\n## Usage\n\nThis example focuses on the OAS docs, registering docs for routes, with schemas from Go types. Routing and server setup is elided.\n\n```golang\nimport (\n  \"encoding/json\"\n  \"net/http\"\n\n  o \"github.com/mitranim/oas\"\n)\n\nvar doc = o.Doc{\n  Openapi: o.Ver,\n  Info:    \u0026o.Info{Title: `API documentation for my server`},\n}\n\ntype PageInput struct {\n  Limit  uint64 `json:\"limit\"`\n  Offset uint64 `json:\"offset\"`\n}\n\ntype PersonPage struct {\n  PageHead\n  Vals []Person `json:\"vals\"`\n}\n\ntype PageHead struct {\n  Keys []string `json:\"keys\"`\n  More bool     `json:\"more\"`\n}\n\ntype Person struct {\n  Id   string `json:\"id\"`\n  Name string `json:\"name\"`\n}\n\nvar _ = doc.Route(`/api/persons`, http.MethodGet, o.Op{\n  ReqBody: doc.JsonBodyOpt(PageInput{}),\n  Resps:   doc.RespsOkJson(PersonPage{}),\n  Desc:    `Serves a single page from a person feed, paginated.`,\n})\n\nfunc servePersonFeed(rew http.ResponseWriter, req *http.Request) {\n  // Mock implementation for example's sake.\n  try(json.NewEncoder(rew).Encode(PersonPage{}))\n}\n\nvar _ = doc.Route(`/openapi.json`, http.MethodGet, o.Op{\n  Resps: doc.RespsOkJson(nil),\n  Desc: `\nServes the OpenAPI documentation for this server in JSON format.\nThe docs' docs are elided from the docs to avoid bloat.\n`,\n})\n\nfunc serveDocs(rew http.ResponseWriter, _ *http.Request) {\n  try(json.NewEncoder(rew).Encode(\u0026doc))\n}\n\nfunc try(err error) {\n  if err != nil {\n    panic(err)\n  }\n}\n```\n\n## Limitations\n\nThe following features are currently missing, but may be added on demand:\n\n* Describing generic/parametrized types.\n  * Current plan: wait for Go generics, which are expected in 1.18 on Feb 2022.\n* Router integration.\n  * Integration with `github.com/mitranim/rout` is planned.\n\nThis package doesn't provide a UI. You're expected to feed the resulting JSON into one of **many** externally-available tools for Swagger UI / OpenAPI UI. Many tools can consume specs from a URL, such as your server's endpoint for serving the spec.\n\n## License\n\nhttps://unlicense.org\n\n## Misc\n\nI'm receptive to suggestions. If this library _almost_ satisfies you but needs changes, open an issue or chat me up. Contacts: https://mitranim.com/#contacts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitranim%2Foas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmitranim%2Foas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmitranim%2Foas/lists"}