{"id":18994061,"url":"https://github.com/swaggest/openapi-go","last_synced_at":"2025-05-15T11:07:55.739Z","repository":{"id":39645435,"uuid":"232207964","full_name":"swaggest/openapi-go","owner":"swaggest","description":"OpenAPI structures for Go","archived":false,"fork":false,"pushed_at":"2025-05-07T21:24:47.000Z","size":484,"stargazers_count":298,"open_issues_count":6,"forks_count":27,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T22:28:23.838Z","etag":null,"topics":["code-generation","documentation-generator","json-schema","openapi","openapi3"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/swaggest/openapi-go/openapi3","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/swaggest.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}},"created_at":"2020-01-07T00:07:41.000Z","updated_at":"2025-05-07T21:24:30.000Z","dependencies_parsed_at":"2023-02-10T18:15:49.341Z","dependency_job_id":"e8ef263f-c667-4962-9f8f-edd2b36fe046","html_url":"https://github.com/swaggest/openapi-go","commit_stats":null,"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fopenapi-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fopenapi-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fopenapi-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fopenapi-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggest","download_url":"https://codeload.github.com/swaggest/openapi-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"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","documentation-generator","json-schema","openapi","openapi3"],"created_at":"2024-11-08T17:24:03.296Z","updated_at":"2025-05-15T11:07:55.715Z","avatar_url":"https://github.com/swaggest.png","language":"Go","readme":"# OpenAPI structures for Go\n\n\u003cimg align=\"right\" width=\"250px\" src=\"/resources/logo.png\"\u003e\n\nThis library provides Go structures to marshal/unmarshal and reflect [OpenAPI Schema](https://swagger.io/resources/open-api/) documents.\n\nFor automated HTTP REST service framework built with this library please check [`github.com/swaggest/rest`](https://github.com/swaggest/rest).\n\n[![Build Status](https://github.com/swaggest/openapi-go/workflows/test/badge.svg)](https://github.com/swaggest/openapi-go/actions?query=branch%3Amaster+workflow%3Atest)\n[![Coverage Status](https://codecov.io/gh/swaggest/openapi-go/branch/master/graph/badge.svg)](https://codecov.io/gh/swaggest/openapi-go)\n[![GoDevDoc](https://img.shields.io/badge/dev-doc-00ADD8?logo=go)](https://pkg.go.dev/github.com/swaggest/openapi-go)\n[![time tracker](https://wakatime.com/badge/github/swaggest/openapi-go.svg)](https://wakatime.com/badge/github/swaggest/openapi-go)\n![Code lines](https://sloc.xyz/github/swaggest/openapi-go/?category=code)\n![Comments](https://sloc.xyz/github/swaggest/openapi-go/?category=comments)\n\n## Features\n\n* Type safe mapping of OpenAPI 3 documents with Go structures generated from schema.\n* Type-based reflection of Go structures to OpenAPI 3.0 or 3.1 schema.\n* Schema control with field tags\n    * `json` for request bodies and responses in JSON\n    * `query`, `path` for parameters in URL\n    * `header`, `cookie`, `formData`, `file` for other parameters\n    * `form` acts as `query` and `formData`\n    * `contentType` indicates body content type\n    * [field tags](https://github.com/swaggest/jsonschema-go#field-tags) named after JSON Schema/OpenAPI 3 Schema constraints\n    * `collectionFormat` to unpack slices from string\n        * `csv` comma-separated values,\n        * `ssv` space-separated values,\n        * `pipes` pipe-separated values (`|`),\n        * `multi` ampersand-separated values (`\u0026`),\n        * `json` additionally to slices unpacks maps and structs,\n* Flexible schema control with [`jsonschema-go`](https://github.com/swaggest/jsonschema-go#implementing-interfaces-on-a-type)\n\n## Example\n\n[Other examples](https://pkg.go.dev/github.com/swaggest/openapi-go/openapi3#pkg-examples).\n\n```go\nreflector := openapi3.Reflector{}\nreflector.Spec = \u0026openapi3.Spec{Openapi: \"3.0.3\"}\nreflector.Spec.Info.\n    WithTitle(\"Things API\").\n    WithVersion(\"1.2.3\").\n    WithDescription(\"Put something here\")\n\ntype req struct {\n    ID     string `path:\"id\" example:\"XXX-XXXXX\"`\n    Locale string `query:\"locale\" pattern:\"^[a-z]{2}-[A-Z]{2}$\"`\n    Title  string `json:\"string\"`\n    Amount uint   `json:\"amount\"`\n    Items  []struct {\n        Count uint   `json:\"count\"`\n        Name  string `json:\"name\"`\n    } `json:\"items\"`\n}\n\ntype resp struct {\n    ID     string `json:\"id\" example:\"XXX-XXXXX\"`\n    Amount uint   `json:\"amount\"`\n    Items  []struct {\n        Count uint   `json:\"count\"`\n        Name  string `json:\"name\"`\n    } `json:\"items\"`\n    UpdatedAt time.Time `json:\"updated_at\"`\n}\n\nputOp, err := reflector.NewOperationContext(http.MethodPut, \"/things/{id}\")\nhandleError(err)\n\nputOp.AddReqStructure(new(req))\nputOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })\nputOp.AddRespStructure(new([]resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusConflict })\n\nreflector.AddOperation(putOp)\n\ngetOp, err := reflector.NewOperationContext(http.MethodGet, \"/things/{id}\")\nhandleError(err)\n\ngetOp.AddReqStructure(new(req))\ngetOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })\n\nreflector.AddOperation(getOp)\n\nschema, err := reflector.Spec.MarshalYAML()\nif err != nil {\n    log.Fatal(err)\n}\n\nfmt.Println(string(schema))\n```\n\nOutput:\n\n```yaml\nopenapi: 3.0.3\ninfo:\n  description: Put something here\n  title: Things API\n  version: 1.2.3\npaths:\n  /things/{id}:\n    get:\n      parameters:\n      - in: query\n        name: locale\n        schema:\n          pattern: ^[a-z]{2}-[A-Z]{2}$\n          type: string\n      - in: path\n        name: id\n        required: true\n        schema:\n          example: XXX-XXXXX\n          type: string\n      responses:\n        \"200\":\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Resp'\n          description: OK\n    put:\n      parameters:\n      - in: query\n        name: locale\n        schema:\n          pattern: ^[a-z]{2}-[A-Z]{2}$\n          type: string\n      - in: path\n        name: id\n        required: true\n        schema:\n          example: XXX-XXXXX\n          type: string\n      requestBody:\n        content:\n          application/json:\n            schema:\n              $ref: '#/components/schemas/Req'\n      responses:\n        \"200\":\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Resp'\n          description: OK\n        \"409\":\n          content:\n            application/json:\n              schema:\n                items:\n                  $ref: '#/components/schemas/Resp'\n                type: array\n          description: Conflict\ncomponents:\n  schemas:\n    Req:\n      properties:\n        amount:\n          minimum: 0\n          type: integer\n        items:\n          items:\n            properties:\n              count:\n                minimum: 0\n                type: integer\n              name:\n                type: string\n            type: object\n          nullable: true\n          type: array\n        string:\n          type: string\n      type: object\n    Resp:\n      properties:\n        amount:\n          minimum: 0\n          type: integer\n        id:\n          example: XXX-XXXXX\n          type: string\n        items:\n          items:\n            properties:\n              count:\n                minimum: 0\n                type: integer\n              name:\n                type: string\n            type: object\n          nullable: true\n          type: array\n        updated_at:\n          format: date-time\n          type: string\n      type: object\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggest%2Fopenapi-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggest%2Fopenapi-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggest%2Fopenapi-go/lists"}