{"id":15176622,"url":"https://github.com/gopenapi/gopenapi","last_synced_at":"2026-03-01T06:33:36.318Z","repository":{"id":57573915,"uuid":"327489646","full_name":"gopenapi/gopenapi","owner":"gopenapi","description":"Gopenapi use javascript to extend and simplify openapi sepc.","archived":false,"fork":false,"pushed_at":"2021-04-09T02:42:10.000Z","size":942,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-22T18:50:14.712Z","etag":null,"topics":["go-openapi","goja","golang","openapi","openapi-generator"],"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/gopenapi.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}},"created_at":"2021-01-07T03:11:52.000Z","updated_at":"2023-02-23T02:21:18.000Z","dependencies_parsed_at":"2022-09-26T19:01:39.330Z","dependency_job_id":null,"html_url":"https://github.com/gopenapi/gopenapi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gopenapi/gopenapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gopenapi%2Fgopenapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gopenapi%2Fgopenapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gopenapi%2Fgopenapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gopenapi%2Fgopenapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gopenapi","download_url":"https://codeload.github.com/gopenapi/gopenapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gopenapi%2Fgopenapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29962026,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"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-openapi","goja","golang","openapi","openapi-generator"],"created_at":"2024-09-27T13:21:56.501Z","updated_at":"2026-03-01T06:33:36.303Z","avatar_url":"https://github.com/gopenapi.png","language":"Go","readme":"\u003cimg align=\"right\" width=\"150px\" src=\"./logo.png\"\u003e\n\n# Gopenapi\nGopenapi use javascript to extend and simplify openapi sepc.\n\n## Goals\nUnlike the regular openapi spec generator, Gopenapi has the following features:\n\n- Highly flexible\n    - Base on openapi.yaml file, you can choose which part of the content is generated by Gopenapi according to your\n      preferences\n    - Use JavaScript to write additional logic\n- Understanding low-cost\n    - Syntax as simple as yaml\n- Less intrusion\n    - Just need a few comments in the go source code\n\n## Why not\n- [go-swagger](https://github.com/go-swagger/go-swagger) has the following disadvantages:\n    - Syntax is complicated, I now need to learn two kinds of syntax: openapi and goswagger\n    - Non-scalability, only the syntax supported by go-swgger can be used\n    - All information is written in Go code, which makes the source code unclean\n\n## Get start\n\n### Precondition\n\n- Make sure your project is written in Golang and 'go module' is enabled\n\n### Step 0: Install Gopenapi\n\n```shell\ngo get -u github.com/gopenapi/gopenapi\n```\n\n### Step 1: Write openapi.src.yaml file\n\n\u003e Gopenapi only support yaml format files so far\n\n```yaml\nopenapi: 3.0.1\ninfo:\n  title: Swagger Petstore\n  description: |\n    This is a sample server Petstore server.  You can find out more about     Swagger\n    at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For\n    this sample, you can use the api key \"special-key\" to test the authorization     filters.\n\n    **All api maybe return 401 code if it need auth.**\n  termsOfService: http://swagger.io/terms/\n  contact:\n    email: apiteam@swagger.io\n  license:\n    name: Apache 2.0\n    url: http://www.apache.org/licenses/LICENSE-2.0.html\n  version: 1.0.0\nexternalDocs:\n  description: Find out more about Swagger\n  url: http://swagger.io\nservers:\n  - url: https://petstore.swagger.io/v2\n  - url: http://petstore.swagger.io/v2\n\ntags:\n  - name: pet\n    description: Test all features\n\npaths:\n  /pet/findByStatus:\n    get:\n      x-$path: github.com/gopenapi/gopenapi/internal/delivery/http/handler.PetHandler.FindPetByStatus\n      tags:\n        - pet\n      security:\n        - petstore_auth:\n            - write:pets\n            - read:pets\n  /pet/{id}:\n    get:\n      x-$path: github.com/gopenapi/gopenapi/internal/delivery/http/handler.PetHandler.GetPet\n      tags:\n        - pet\n      operationId: getPetById\n      security:\n        - api_key: [ ]\n\n    delete:\n      x-$path: ./internal/delivery/http/handler.PetHandler.DelPet\n      tags:\n        - pet\n      security:\n        - api_key: [ ]\n\ncomponents:\n  schemas:\n    Category:\n      x-$schema: github.com/gopenapi/gopenapi/internal/model.Category\n    Tag:\n      x-$schema: ./internal/model.Tag\n    Pet:\n      x-$schema: github.com/gopenapi/gopenapi/internal/model.Pet\n```\n\nAs you can see, Gopenapi provide some extended syntax:\n\n- x-$schema\n- x-$path\n\nFor more information about 'extended syntax', please refer to [here](#Extended-Syntax)\n\n### Step 2: Write 'meta-comments' in your go source code\n\n```diff\n// FindPetByStatus Finds Pets by status\n//\n+ // $:\n+ //   params: model.FindPetByStatusParams\n+ //   response: schema([model.Pet])\nfunc (h *PetHandler) FindPetByStatus(ctx *gin.Context) {\n...\n}\n```\n\n**Done! Just added 3 lines of comments**\n\n'meta-comments' syntax is yaml, but it needs to start with the '$' symbol.\n\nThe following syntax is correct:\n\n```\n// $:\n//   params: model.FindPetByStatusParams\n//   response: schema([model.Pet])\n```\n\nor\n\n```\n// $:\n//   params: model.FindPetByStatusParams\n//   response: \n//     200: schema([model.Pet])\n```\n\nor\n\n```\n// $params: model.FindPetByStatusParams\n// $response: schema([model.Pet])\n```\n\n\u003e Remember it just is 'yaml'\n\n### Step 3: Run Gopenapi to fill your yaml file\n\nRun the following command in the project root directory.\n```bash\ngopenapi -i example/openapi.src.yaml -o example/openapi.gen.yaml\n```\n\nTip: Type 'gopenapi -h' for more helps.\n\n```bash\ngopenapi -h\n\nUsage:\n  gopenapi [flags]\n\nFlags:\n  -c, --config string   specify the configuration file to be used (default \"gopenapi.conf.js\")\n  -h, --help            help for gopenapi\n  -i, --input string    specify the source file in yaml format\n  -o, --output string   specify the output file path\n  -v, --version         version for gopenapi\n\n```\n\n\u003e Tip: You can review the generated file on http://editor.swagger.io/\n\n## Extended Syntax\n\n#### x-$path\n\nThe x-$path instruction generates data that conforms to `openapi-path` from Go comment.\n\nIts value is the definition path of function or struct.\n\ne.g.\n\n- github.com/gopenapi/gopenapi/internal/delivery/http/handler.PetHandler.FindPetByStatus\n- ./internal/delivery/http/handler.PetHandler.FindPetByStatus\n\n#### x-$schema\n\nThe x-$schema instruction generates data that conforms to `openapi-schema` from Go struct.\n\nIts value is the definition path of struct.\n\ne.g.\n\n- github.com/gopenapi/gopenapi/internal/model.Pet\n- ./internal/model.Pet\n\n#### x-$tags\n\nSame as `tags`, except that the group field is added to generate 'x-tagGroups'\nfor [redoc](https://github.com/Redocly/redoc).\n\ninput\n\n```yaml\n\nx-$tags:\n  - name: Regular\n    description: Test all features\n    group: GroupA\n  - name: Edge\n    description: Test things that are prone to bugs\n    group: GroupB\n```\n\noutput\n\n```yaml\ntags:\n  - name: Regular\n    description: Test all features\n  - name: Edge\n    description: Test things that are prone to bugs\nx-tagGroups:\n  - name: GroupA\n    tags:\n      - Regular\n  - name: GroupB\n    tags:\n      - Edge\n```\n\n## Shortcoming\n\n- Currently, this project is still being tested, Performance is not stable enough, code is not elegant enough.\n- Since it is based on Golang Ast, it currently **only supports Golang**, and need to enable 'go module'.\n\n## Who needs Gopenapi?\n\nIf you meet the following situation, maybe you need it\n\n- Not using openapi\n- Write openapi.yaml by yourself\n\nDon't recommend you who are using go-swagger to use it, unless you want to write `openapi.yaml` again.\n\n## Advanced\n\nSo far you already know how to use Gopenapi, if you want more customization, please read on.\n\n### What is `gopenapi.conf.js`?\n\nGopenapi will generate `gopenapi.conf.js` file in the root directory of the project after running if this file does not\nexist.\n\nYou can make more custom syntax in this script (In addition to cross-language syntax, such as the functions provided by\nx-$path, it is built in Gopenapi. nevertheless, you can still customize the format of 'meta-comment').\n\nFor example, the x-$path syntax currently supports multiple formats of 'meta-comment':\n\nin yaml\n\n```yaml\nx-$path: ./internal/delivery/http/handler.PetHandler.FindPetByStatus\n```\n\nin go code\n\n```\n// add 'required' field\n// \n// $:\n//   params: {schema: model.FindPetByStatusParams, required: [status]}\n//   response: model.Pet\n\nor\n\n// add 'description' field\n// \n// $:\n//   params: {schema: model.FindPetByStatusParams, required: [status]}\n//   response: {schema: model.Pet, desc: 'success!'}\n\nor\n\n// add more responses\n// \n// $:\n//   params: {schema: model.FindPetByStatusParams, required: [status]}\n//   response: {200: {schema: model.Pet, desc: 'success!'}, 401: '#401'} \n\nor\n\n// add 'tag' field\n// \n// $:\n//   params: {schema: model.FindPetByStatusParams, required: [status]}\n//   response: {200: {schema: model.Pet, desc: 'success!'}, 401: '#401'} \n//   tags: [pet]\n```\n\n### How to write `gopenapi.conf.js`?\n\nThe code in `gopenapi.conf.js` is very long, I do not recommend you to modify it, you can create a new issue if you have\nsame requirements.\n\nIf you really want to modify it, don’t worry about breaking it, just delete it and run gopenapi again will regenerate\nit.\n\nFor example, if we want to add a `operationId` field, we can write code like this:\n\nIn go comments:\n\n```diff\n// $:\n//   params: model.FindPetByStatusParams\n//   response: schema([model.Pet]) \n//   tags: [pet]\n+ //   operationId: FindPetByStatus\n```\n\nIn `gopenapi.conf.js`:\n\n```diff\nexport default {\n  filter: function (key, value) {\n    ...\n    let path = {\n      summary: value.summary,\n      description: value.description,\n    }\n     // use 'console.log(JSON.stringify(value))' to print data-struct of value\n+    if (value.meta.operationId) {\n+      path.operationId = value.meta.operationId\n+    }\n    ...\n```\n\nNow the generated openapi will add the `operationId` field\n```diff\npaths:\n  /pet/findByStatus:\n    get:\n+      operationId: FindPetByStatus\n      summary: FindPetByStatus test for return array schema\n      description: \"\"\n      ...\n```\n\n## FQA\n\n#### How to distinguish whether the string in 'meta-comments' is JavaScript or pure string?\n\n```\n// $:\n//   params: model.FindPetByStatusParams\n```\n\nIn the above example, 'model.FindPetByStatusParams' will be parsed into JavaScript execution instead of pure string,\nbecause Gopenapi can guessing whether the string is JavaScript or not.\n\nStrings that meet the following rules will be executed as JavaScript:\n\n- Wrap with '[]'\n- Wrap with '{}'\n- Wrap with 'schema()'\n- string like \"model.X\" and can find the definition in go source code.\n\n## Next goal\n\n- Optimize code and performance\n- More documentation if you need it\n- Organize the code in `gopenapi.conf.js`\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgopenapi%2Fgopenapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgopenapi%2Fgopenapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgopenapi%2Fgopenapi/lists"}