{"id":18309386,"url":"https://github.com/masterjoyhunan/gen-swagger","last_synced_at":"2025-04-09T11:32:22.910Z","repository":{"id":238658307,"uuid":"784690250","full_name":"MasterJoyHunan/gen-swagger","owner":"MasterJoyHunan","description":"基于 go-zero api 文件生成 swagger.json 的工具","archived":false,"fork":false,"pushed_at":"2024-07-23T03:04:29.000Z","size":67,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-15T05:30:23.727Z","etag":null,"topics":[],"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/MasterJoyHunan.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}},"created_at":"2024-04-10T11:06:47.000Z","updated_at":"2024-08-04T13:10:13.000Z","dependencies_parsed_at":"2024-06-19T11:18:55.423Z","dependency_job_id":"317aa00f-cf3c-4173-bd8e-cfa0eac36439","html_url":"https://github.com/MasterJoyHunan/gen-swagger","commit_stats":null,"previous_names":["masterjoyhunan/gen-swagger"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasterJoyHunan%2Fgen-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasterJoyHunan%2Fgen-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasterJoyHunan%2Fgen-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MasterJoyHunan%2Fgen-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MasterJoyHunan","download_url":"https://codeload.github.com/MasterJoyHunan/gen-swagger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248031711,"owners_count":21036456,"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":[],"created_at":"2024-11-05T16:11:17.120Z","updated_at":"2025-04-09T11:32:22.869Z","avatar_url":"https://github.com/MasterJoyHunan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"### gen-swagger\n\n基于 go-zero api 文件生成 swagger.json 的工具\n\n\u003e 个人觉得 swagger 是一个非常好用的文档工具，go-zero 官方也有同样的 swagger 工具，但是不怎么维护了，\n\u003e 提交的 issue 也无法及时处理。没办法，想着自己写一个算了，于是有了这个项目\n\n### 基本使用\n\n#### 安装\n\ngo 1.16 以下使用\n```sh\ngo get -u github.com/MasterJoyHunan/gen-swagger\n```\n\ngo 1.16 及以上使用\n```sh\ngo install github.com/MasterJoyHunan/gen-swagger@v1.0.5\n```\n\n#### 在项目下定义 you-app.api 文件\n\n[api语法指南](https://go-zero.dev/docs/tutorials)\n\nyou-app.api 文件内容示例\n\n```api\nsyntax = \"v1\"\n\ninfo(\n\ttitle: \"some app\"\n)\n\ntype bookRequest {\n    Name string `json:\"name\"` // 姓名\n    Age int `json:\"age\"`      // 年龄\n}\n\ntype bookResponse {\n    Code int `json:\"code\"` // 业务码\n    Msg string `json:\"msg\"` // 业务消息\n}\n\n@server(\n    jwt: Auth\n    group: book\n    middleware: SomeMiddleware,CorsMiddleware\n    prefix: /v1\n)\n\nservice someapp {\n    @doc \"获取所有书本信息\"\n    @handler getBookList\n    get /book (bookRequest) returns (bookResponse)\n\n    @doc \"获取书本信息\"\n    @handler getBook\n    get /book/:id (bookRequest) returns (bookResponse)\n\n    @doc \"添加书本信息\"\n    @handler addBook\n    post /book (bookRequest) returns (bookResponse)\n\n    @doc \"获取书本信息\"\n    @handler editBook\n    put /book/:id (bookRequest) returns (bookResponse)\n}\n```\n\n#### 生成 swagger.json 文件\n\n```sh\ngen-swagger --local_api=http://127.0.0.1:8888 --file=asset/swagger/swagger.json broadband-management-api.api\n```\n\n参数说明\n\n* --file 生成swagger文件路径 | 默认:asset/swagger/swagger.json\n* --auth_name 权限认证请求名 | 默认:Authorization\n* --auth_position 权限认证请求位置 header,query,cookie | 默认:header\n* --local_api 本地环境请求地址 | 默认:http://127.0.0.1:8888\n* --dev_api 测试环境请求地址\n* --prod_api 生产环境请求地址\n\n#### 准备前端页面 swagger.html\n\n```html\n\u003c!-- HTML for static distribution bundle build --\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003ctitle\u003e{{ .Title }}\u003c/title\u003e\n    \u003clink rel=\"stylesheet\" type=\"text/css\" href=\"https://petstore.swagger.io/swagger-ui.css\" \u003e\n    \u003clink rel=\"icon\" type=\"image/png\" href=\"https://petstore.swagger.io/favicon-32x32.png\" sizes=\"32x32\" /\u003e\n    \u003clink rel=\"icon\" type=\"image/png\" href=\"https://petstore.swagger.io/favicon-16x16.png\" sizes=\"16x16\" /\u003e\n    \u003cstyle\u003e\n        html\n        {\n            box-sizing: border-box;\n            overflow: -moz-scrollbars-vertical;\n            overflow-y: scroll;\n        }\n        *,\n        *:before,\n        *:after\n        {\n            box-sizing: inherit;\n        }\n        body\n        {\n            margin:0;\n            background: #fafafa;\n        }\n    \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cdiv id=\"swagger-ui\"\u003e\u003c/div\u003e\n\u003cscript src=\"https://petstore.swagger.io/swagger-ui-bundle.js\"\u003e \u003c/script\u003e\n\u003cscript src=\"https://petstore.swagger.io/swagger-ui-standalone-preset.js\"\u003e \u003c/script\u003e\n\u003cscript\u003e\n    window.onload = function() {\n        // Begin Swagger UI call region\n        const ui = SwaggerUIBundle({\n            \"dom_id\": \"#swagger-ui\",\n            deepLinking: true,\n            presets: [\n                SwaggerUIBundle.presets.apis,\n                SwaggerUIStandalonePreset\n            ],\n            plugins: [\n                SwaggerUIBundle.plugins.DownloadUrl\n            ],\n            layout: \"StandaloneLayout\",\n            defaultModelsExpandDepth: -1,\n            defaultModelExpandDepth: 5,\n            validatorUrl: null,\n            url: \"{{ .SpecURL }}\",\n        })\n        // End Swagger UI call region\n        window.ui = ui\n    }\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n\n```\n\n#### 替换模板文件\n\n以 gin 框架为例\n\n\n```go\npackage main\n\nimport (\n\t\"bytes\"\n\t_ \"embed\"\n\t\"text/template\"\n\t\"github.com/gin-gonic/gin\"\n)\n\n//go:embed swagger.html\nvar swaggerHtml string\n\n// Setup 生成 swagger 格式的文档\nfunc main() {\n    c := gin.New()\n    c.GET(\"/swagger\", func(ctx *gin.Context) {\n        ctx.Header(\"Content-Type\", \"text/html; charset=utf-8\")\n        tpl := template.Must(template.New(\"doc\").Parse(swaggerHtml))\n        buf := bytes.NewBuffer(nil)\n        tpl.Execute(buf, map[string]string{\n            \"Title\":   \"接口使用文档\",\n            \"SpecURL\": \"/swaggerfs/swagger.json\",\n        })\n        ctx.Writer.Write(buf.Bytes())\n    })\n\n    c.Static(\"/swaggerfs\", \"asset/swagger\")\n    c.Run(\":80\")\n}\n```\n\n### 最终效果\n\n![image-20240509171735559](http://tc.masterjoy.top/typory/image-20240509171735559.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasterjoyhunan%2Fgen-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasterjoyhunan%2Fgen-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasterjoyhunan%2Fgen-swagger/lists"}