{"id":36656859,"url":"https://github.com/fmarmol/openapigen","last_synced_at":"2026-01-12T10:20:49.420Z","repository":{"id":289484170,"uuid":"904763646","full_name":"fmarmol/openapigen","owner":"fmarmol","description":"openapi yaml generation directly from golang","archived":false,"fork":false,"pushed_at":"2025-09-20T12:18:11.000Z","size":359,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-20T14:20:27.164Z","etag":null,"topics":["generator","golang","openapi","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","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/fmarmol.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-17T14:02:51.000Z","updated_at":"2025-09-20T12:18:15.000Z","dependencies_parsed_at":"2025-06-11T08:35:52.316Z","dependency_job_id":"a6599fa9-e77f-407e-bf5c-706819488efc","html_url":"https://github.com/fmarmol/openapigen","commit_stats":null,"previous_names":["fmarmol/openapigen"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fmarmol/openapigen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmarmol%2Fopenapigen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmarmol%2Fopenapigen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmarmol%2Fopenapigen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmarmol%2Fopenapigen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fmarmol","download_url":"https://codeload.github.com/fmarmol/openapigen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fmarmol%2Fopenapigen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"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":["generator","golang","openapi","yaml"],"created_at":"2026-01-12T10:20:47.124Z","updated_at":"2026-01-12T10:20:49.399Z","avatar_url":"https://github.com/fmarmol.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openapigen\n\n:warning: This package is in early development. Breaking changes can occur in next phases of development.\n\n## Goal\nUse DSL like written in go to build your openapi yaml files.\n\n## TOC\n- [Installation](#installation)\n- [Getting started](#getting-started)\n- [Routing](#routing)\n- [Parameters](#parameters)\n- [Request Body description](#request-body)\n- [Response Body description](#response-body)\n- [Fields description](#fields)\n- [Enums](#enums)\n- [Extensions](#extensions)\n- [Additional properties](#additional-properties)\n- [Generics](#generics)\n\n### Installation\n```sh\ngo get github.com/fmarmol/openapigen@latest\n```\n\n### Getting started\n\n```go\npackage main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"github.com/fmarmol/openapigen\"\n)\n\ntype Movie struct {\n\tTitle string `json:\"title\"`\n\tYear  int    `json:\"year\"`\n}\n\ntype Movies []Movie\n\nfunc generateDoc() error {\n\tdoc := openapigen.Document{Title: \"my api\", Version: \"1.0\"}\n\tdoc.Paths(\n\t\topenapigen.NewPath(\"/movies\").Get().\n\t\t\tDescription(\"return a list of movies\").\n\t\t\tResponses(\n\t\t\t\topenapigen.NewResponse(200).JSON(Movies{}).Description(\"success\"),\n\t\t\t),\n\t)\n\treturn doc.Write(os.Stdout, 2)\n}\n\nfunc main() {\n\t_ = generateDoc()\n\thttp.HandleFunc(\"GET /movies\", func(w http.ResponseWriter, r *http.Request) {\n\t\tw.Header().Set(\"content-type\", \"application/json\")\n\n\t\tmovies := []Movie{\n\t\t\t{Title: \"star wars\", Year: 1977},\n\t\t\t{Title: \"matrix\", Year: 1999},\n\t\t}\n\t\tw.WriteHeader(200)\n\t\t_ = json.NewEncoder(w).Encode(movies)\n\t})\n\t_ = http.ListenAndServe(\":8080\", nil)\n}\n```\n\nWe'll give the following result:\n\n```sh\nopenapi: 3.0.0\ninfo:\n  title: my api\n  version: \"1.0\"\nsecurity: null\ntags: null\npaths:\n  /movies:\n    get:\n      description: return a list of movies\n      responses:\n        \"200\":\n          content:\n            application/json:\n              schema:\n                $ref: '#/components/schemas/Movies'\n          description: success\n        default:\n          description: \"\"\ncomponents:\n  schemas:\n    Movie:\n      properties:\n        title:\n          type: string\n        year:\n          type: integer\n      type: object\n    Movies:\n      items:\n        $ref: '#/components/schemas/Movie'\n      type: array\n```\n\n## Routing\nIn every rest API you have to choose an HTTP method for each of your route. In openapigen you write the same by using one the following methods:\n\n```go\n  Path.Get()\n  Path.Post()\n  Path.Put()\n  Path.Patch()\n  Path.Delete()\n  Path.Options()\n  Path.Connect()\n  Path.Trace()\n```\n\n## Parameters\nWhat would be an api without path or query parameters, you can easily describe these parameters using the following methods.\n\n### path parameters\nFor example if you have an endpoint using an `uuid` to get information about a user\nlike `/api/users/{id}`\n\n```go\nParameter(NewParameter().InPath().Name(\"id\").Type(\"string\").Format(\"uuid\").Required())\n```\n\n### query parameters\nYou can also do the same using query parameters like `/api/users?id={id}`\n\n```go\nParameter(NewParameter().InQuery().Name(\"id\").Type(\"string\").Format(\"uuid\").Required())\n```\n\nIn this case the `Required()` can be omitted, if the parameter is optional\n\n## Request Body\nFor almost anything which is not a `GET` request you need to specify the body of your request.\n\nFor now the formats supported are:\n- JSON with the method `JsonBody`\n- Multipart/form-data with the method `FormData`\n\n\nexample:\n\n```go\nJsonBody(Movie{}, true) // true is optional and means the body is required\n```\n\n## Response Body\nThe same way for the response body which returns you api call, you can use your types using the method `JSON`\n\n\n```go\nResponses(\n  NewResponse(200).JSON(Movie{}).Description(\"return a movie object\"),\n)\n```\n\nOnly `JSON` is currently supported\n\n## Fields\n\nUsing go structures, allow you to specify the fields in the request and response body. All exported fields will be translated into openapi components schemas.\nThe default behaviour will transform the fields name into optional `snake_case` openapi fields.\n\nTo have a better control on what you want to express, here a list of tags you can use.\n\n- `name`\n- `format`\n- `description`\n- `deprecated`\n- `default`\n- `min`\n- `max`\n- `required`\n- `nullable`\n\n\nGo natives types are turned into:\n\n| types | openapi |\n|-------|---------|\n|int8, int16, int | `type:\"integer\"`              |\n|int32            | `type:\"int32\"`                |\n|int64            | `type:\"int,format:in64\"`      |\n|float32          | `type:\"number,format:double\"` |\n|float64          | `type:\"number,format:float\"`  |\n|bool             | `type:\"boolean\"`                |\n\nFew non primitive types are automatically preconfigured like:\n- time.Time which is equivalent to `format:date-time`\n- uuid.UUID wich is equivalent to `type:string,format:uuid` from `github.com/google/uuid` \n\n### Enums\n\nIts quite common to have fields which can have only a set of values. They are enums, in order to express it into openapi you have to write a custom type\nfor the enum fields which implement the Enum interface\n\n```go\ntype Enum interface{\n  Value() []any\n}  \n```\n\nfor example:\n\n```go\n\n  type Gender string\n\n  func (Gender) Values() []any{\n    return []any{\"male\", \"female\"}\n  }\n\n  type User struct {\n    Gender Gender\n  }\n```\n\n#### Enums in parameters\nYou can also express enums in parameters using the method `Enum`\n\n```go\nParameter(NewParameter().InQuery().Name(\"gender\").Enum(Gender{}))\n```\n\n## Extensions\n\nSee notes [here](https://swagger.io/docs/specification/v3_0/openapi-extensions/)\n\nYou can specify extensions on schema's fields with the `ExtenstionI` interface.\n\n```go\n  type Extensions = map[string]any\n  type FieldName = string // its the field name in the go struct\n\n  type ExtensionsI interface {\n  \tExtensions() map[FieldName]Extensions\n  }\n```\n\nLet's take an example where you have a `Request` struct containing a field `MustBeThere`\n\n```go\nfunc (Request) Extensions() map[string]map[string]any {\n\treturn map[string]map[string]any{\"MustBeThere\": {\n\t\t\"x-go-type-skip-optional-pointer\": true,\n\t}}\n}\n```\n\n`x-go-type-skip-optional-pointer` is an extension supported by the project [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen)\nto remove pointer on field in golang code generation.\n\n### Self extensions\n\n## Additional properties\n\n## Generics (beta)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmarmol%2Fopenapigen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffmarmol%2Fopenapigen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffmarmol%2Fopenapigen/lists"}