{"id":207748,"date":"2025-07-08T08:15:54","date_gmt":"2025-07-08T00:15:54","guid":{"rendered":"https:\/\/server.hk\/cnblog\/207748\/"},"modified":"2025-07-08T08:15:54","modified_gmt":"2025-07-08T00:15:54","slug":"%e5%a6%82%e4%bd%95%e4%bb%8ego%e6%ba%90%e4%bb%a3%e7%a0%81%e7%94%9f%e6%88%90openapi-v3%e8%a7%84%e8%8c%83%ef%bc%9f","status":"publish","type":"post","link":"https:\/\/server.hk\/cnblog\/207748\/","title":{"rendered":"\u5982\u4f55\u4eceGo\u6e90\u4ee3\u7801\u751f\u6210OpenAPI v3\u89c4\u8303\uff1f"},"content":{"rendered":"

<\/b> <\/p>\n

\u5f53\u524d\u4f4d\u7f6e\uff1a ><\/span> ><\/span> ><\/span> ><\/span> \u5982\u4f55\u4eceGo\u6e90\u4ee3\u7801\u751f\u6210OpenAPI v3\u89c4\u8303\uff1f<\/span><\/p>\n

\u6765\u6e90\uff1astackoverflow<\/span>
\n2024-04-25 12:03:33<\/span>
\n<\/i>0\u6d4f\u89c8<\/span>
\n<\/i>\u6536\u85cf<\/span> <\/p>\n

\u4eb2\u7231\u7684\u7f16\u7a0b\u5b66\u4e60\u7231\u597d\u8005\uff0c\u5982\u679c\u4f60\u70b9\u5f00\u4e86\u8fd9\u7bc7\u6587\u7ae0\uff0c\u8bf4\u660e\u4f60\u5bf9\u300a\u5982\u4f55\u4eceGo\u6e90\u4ee3\u7801\u751f\u6210OpenAPI v3\u89c4\u8303\uff1f\u300b\u5f88\u611f\u5174\u8da3\u3002\u672c\u7bc7\u6587\u7ae0\u5c31\u6765\u7ed9\u5927\u5bb6\u8be6\u7ec6\u89e3\u6790\u4e00\u4e0b\uff0c\u4e3b\u8981\u4ecb\u7ecd\u4e00\u4e0b\uff0c\u5e0c\u671b\u6240\u6709\u8ba4\u771f\u8bfb\u5b8c\u7684\u7ae5\u978b\u4eec\uff0c\u90fd\u6709\u5b9e\u8d28\u6027\u7684\u63d0\u9ad8\u3002<\/p>\n

\u95ee\u9898\u5185\u5bb9
\n <\/p>\n

\u6709\u6ca1\u6709\u529e\u6cd5\u4ecego\u6e90\u4ee3\u7801\u751f\u6210openapi v3\u89c4\u8303\uff1f\u5047\u8bbe\u6211\u53ef\u4ee5\u5c1d\u8bd5\u4e00\u4e0b \u50cf\u4e0b\u9762\u8fd9\u6837\u7684 api\uff0c\u6211\u60f3\u4ece\u4e2d\u751f\u6210 openapi \u89c4\u8303\uff08yaml \u6587\u4ef6\uff09\u3002\u7c7b\u4f3c\u4e8epython\u7684flask restx\u3002\u6211\u77e5\u9053\u6709\u4e00\u4e9b\u5de5\u5177\u53ef\u4ee5\u6839\u636e\u89c4\u8303\u751f\u6210 go \u6e90\u4ee3\u7801\uff0c\u4f46\u662f\uff0c\u6211\u60f3\u4ee5\u76f8\u53cd\u7684\u65b9\u5f0f\u8fdb\u884c\u64cd\u4f5c\u3002<\/p>\n

package main\n\nimport \"net\/http\"\n\nfunc main() {\n    http.HandleFunc(\"\/hello\", func(w http.ResponseWriter, r *http.Request) {\n        w.Write([]byte(\"world\\n\"))\n    })\n    http.ListenAndServe(\":5050\", nil)\n}\n<\/pre>\n
 <\/p>\n
\u89e3\u51b3\u65b9\u6848<\/h2>\n
 <\/p>\n
\u60a8\u53ef\u4ee5\u4f7f\u7528 \u6784\u5efa\u81ea\u8bb0\u5f55 http rest api\u3002\u8be5\u5e93\u5efa\u7acb\u4e86\u4e00\u4e2a\u7ea6\u5b9a\uff0c\u4ee5\u53ef\u7528\u4e8e\u53cd\u6620\u6587\u6863\u548c\u6a21\u5f0f\u5e76\u7ef4\u62a4\u6709\u5173\u5b83\u7684\u5355\u4e00\u4e8b\u5b9e\u6765\u6e90\u7684\u65b9\u5f0f\u58f0\u660e\u5904\u7406\u7a0b\u5e8f\u3002<\/p>\n
\u6211\u4e2a\u4eba\u8ba4\u4e3a\uff0c\u4e0e\u89c4\u8303\u4f18\u5148\u65b9\u6cd5\u76f8\u6bd4\uff0c\u4ee3\u7801\u4f18\u5148\u65b9\u6cd5\u5177\u6709\u4f18\u52bf\u3002\u5b83\u4e0d\u9700\u8981\u6210\u4e3a\u89c4\u8303\u8bed\u8a00\u8bed\u6cd5\u65b9\u9762\u7684\u4e13\u5bb6\uff0c\u56e0\u6b64\u53ef\u4ee5\u964d\u4f4e\u5165\u95e8\u95e8\u69db\u3002\u5b83\u53ef\u80fd\u6709\u52a9\u4e8e\u63d0\u51fa\u4e00\u4e2a\u4e0e\u5b9e\u73b0\u7ec6\u8282\u5f88\u597d\u5e73\u8861\u7684\u89c4\u8303\u3002<\/p>\n
\u4f7f\u7528\u4ee3\u7801\u4f18\u5148\u65b9\u6cd5\uff0c\u65e0\u9700\u5b9e\u73b0\u5b8c\u6574\u7684\u670d\u52a1\u6765\u83b7\u53d6\u89c4\u8303\u3002\u60a8\u53ea\u9700\u8981\u5b9a\u4e49\u7ed3\u6784\u548c\u63a5\u53e3\uff0c\u53ef\u4ee5\u63a8\u8fdf\u5b9e\u9645\u7684\u903b\u8f91\u5b9e\u73b0\u3002<\/p>\n
\u8bf7\u67e5\u770b\u7b80\u5355\u4f7f\u7528\u3002<\/p>\n
package main\n\nimport (\n    \"context\"\n    \"errors\"\n    \"fmt\"\n    \"log\"\n    \"net\/http\"\n    \"time\"\n\n    \"github.com\/go-chi\/chi\"\n    \"github.com\/go-chi\/chi\/middleware\"\n    \"github.com\/swaggest\/rest\"\n    \"github.com\/swaggest\/rest\/chirouter\"\n    \"github.com\/swaggest\/rest\/jsonschema\"\n    \"github.com\/swaggest\/rest\/nethttp\"\n    \"github.com\/swaggest\/rest\/openapi\"\n    \"github.com\/swaggest\/rest\/request\"\n    \"github.com\/swaggest\/rest\/response\"\n    \"github.com\/swaggest\/rest\/response\/gzip\"\n    \"github.com\/swaggest\/swgui\/v3cdn\"\n    \"github.com\/swaggest\/usecase\"\n    \"github.com\/swaggest\/usecase\/status\"\n)\n\nfunc main() {\n    \/\/ init api documentation schema.\n    apischema := &openapi.collector{}\n    apischema.reflector().specens().info.title = \"basic example\"\n    apischema.reflector().specens().info.withdescription(\"this app showcases a trivial rest api.\")\n    apischema.reflector().specens().info.version = \"v1.2.3\"\n\n    \/\/ setup request decoder and validator.\n    validatorfactory := jsonschema.newfactory(apischema, apischema)\n    decoderfactory := request.newdecoderfactory()\n    decoderfactory.applydefaults = true\n    decoderfactory.setdecoderfunc(rest.paraminpath, chirouter.pathtourlvalues)\n\n    \/\/ create router.\n    r := chirouter.newwrapper(chi.newrouter())\n\n    \/\/ setup middlewares.\n    r.use(\n        middleware.recoverer,                          \/\/ panic recovery.\n        nethttp.openapimiddleware(apischema),          \/\/ documentation collector.\n        request.decodermiddleware(decoderfactory),     \/\/ request decoder setup.\n        request.validatormiddleware(validatorfactory), \/\/ request validator setup.\n        response.encodermiddleware,                    \/\/ response encoder setup.\n        gzip.middleware,                               \/\/ response compression with support for direct gzip pass through.\n    )\n\n    \/\/ create use case interactor.\n    u := usecase.iointeractor{}\n\n    \/\/ describe use case interactor.\n    u.settitle(\"greeter\")\n    u.setdescription(\"greeter greets you.\")\n\n    \/\/ declare input port type.\n    type helloinput struct {\n        locale string `query:\"locale\" default:\"en-us\" pattern:\"^[a-z]{2}-[a-z]{2}$\" enum:\"ru-ru,en-us\"`\n        name   string `path:\"name\" minlength:\"3\"` \/\/ field tags define parameter location and json schema constraints.\n    }\n    u.input = new(helloinput)\n\n    \/\/ declare output port type.\n    type hellooutput struct {\n        now     time.time `header:\"x-now\" json:\"-\"`\n        message string    `json:\"message\"`\n    }\n    u.output = new(hellooutput)\n\n    u.setexpectederrors(status.invalidargument)\n    messages := map[string]string{\n        \"en-us\": \"hello, %s!\",\n        \"ru-ru\": \"\u041f\u0440\u0438\u0432\u0435\u0442, %s!\",\n    }\n    u.interactor = usecase.interact(func(ctx context.context, input, output interface{}) error {\n        var (\n            in  = input.(*helloinput)\n            out = output.(*hellooutput)\n        )\n\n        msg, available := messages[in.locale]\n        if !available {\n            return status.wrap(errors.new(\"unknown locale\"), status.invalidargument)\n        }\n\n        out.message = fmt.sprintf(msg, in.name)\n        out.now = time.now()\n\n        return nil\n    })\n\n    \/\/ add use case handler to router.\n    r.method(http.methodget, \"\/hello\/{name}\", nethttp.newhandler(u))\n\n    \/\/ swagger ui endpoint at \/docs.\n    r.method(http.methodget, \"\/docs\/openapi.json\", apischema)\n    r.mount(\"\/docs\", v3cdn.newhandler(apischema.reflector().spec.info.title,\n        \"\/docs\/openapi.json\", \"\/docs\"))\n\n    \/\/ start server.\n    log.println(\"http:\/\/localhost:8011\/docs\")\n    if err := http.listenandserve(\":8011\", r); err != nil {\n        log.fatal(err)\n    }\n}<\/pre>\n
\u60a8\u53ef\u4ee5\u4f7f\u7528 \uff08\u5b8c\u5168\u516c\u5f00\uff1a\u6211\u662f\u4f5c\u8005\uff09\u4ece go \u4ee3\u7801\u751f\u6210 openapi 3.1 \u548c json schema\uff0c\u5b83\u9002\u7528\u4e8e\u5404\u79cd\u6d41\u884c\u7684\u8def\u7531\u5668\uff0c\u56e0\u6b64\u53ef\u4ee5\u6839\u636e\u9700\u8981\u96c6\u6210\u5230\u73b0\u6709\u4ee3\u7801\u5e93\u4e2d\u3002 huma \u5229\u7528 go \u6cdb\u578b\u4e3a\u8f93\u5165\u53c2\u6570\u3001\u4e3b\u4f53\u3001\u54cd\u5e94\u5934\u7b49\u63d0\u4f9b\u7f16\u8bd1\u65f6\u68c0\u67e5\u3002<\/p>\n
\u8fd9\u662f\u4e00\u4e2a\u7b80\u5355\u7684 hello world \u793a\u4f8b\uff0c\u53ea\u6709\u51e0\u884c\uff1a<\/p>\n
package main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"net\/http\"\n\n    \"github.com\/danielgtaylor\/huma\/v2\"\n    \"github.com\/danielgtaylor\/huma\/v2\/adapters\/humachi\"\n    \"github.com\/go-chi\/chi\/v5\"\n)\n\n\/\/ greetinginput represents the greeting operation request.\ntype greetinginput struct {\n    name string `path:\"name\" maxlength:\"30\" example:\"world\" doc:\"name to greet\"`\n}\n\n\/\/ greetingoutput represents the greeting operation response.\ntype greetingoutput struct {\n    body struct {\n        message string `json:\"message\" example:\"hello, world!\" doc:\"greeting message\"`\n    }\n}\n\nfunc main() {\n    \/\/ create a new router & api\n    router := chi.newmux()\n    api := humachi.new(router, huma.defaultconfig(\"my api\", \"1.0.0\"))\n\n    \/\/ register get \/greeting\/{name}\n    huma.register(api, huma.operation{\n        operationid: \"get-greeting\",\n        summary:     \"get a greeting\",\n        method:      http.methodget,\n        path:        \"\/greeting\/{name}\",\n    }, func(ctx context.context, input *greetinginput) (*greetingoutput, error) {\n        resp := &greetingoutput{}\n        resp.body.message = fmt.sprintf(\"hello, %s!\", input.name)\n        return resp, nil\n    })\n\n    \/\/ start the server!\n    http.listenandserve(\"127.0.0.1:8888\", router)\n}\n<\/pre>\n
\u7136\u540e\u60a8\u53ef\u4ee5\u8f7b\u677e\u5730\u4ece\u670d\u52a1\u83b7\u53d6\u751f\u6210\u7684 openapi\uff1a<\/p>\n
curl http:\/\/localhost:8888\/openapi.json\n<\/pre>\n
\u60a8\u8fd8\u53ef\u4ee5\u5728 http:\/\/localhost:8888\/docs<\/code> \u67e5\u770b openapi \u751f\u6210\u7684\u6587\u6863\u3002<\/p>\n
\u4eca\u5929\u5173\u4e8e\u300a\u5982\u4f55\u4eceGo\u6e90\u4ee3\u7801\u751f\u6210OpenAPI v3\u89c4\u8303\uff1f\u300b\u7684\u5185\u5bb9\u4ecb\u7ecd\u5c31\u5230\u6b64\u7ed3\u675f\uff0c\u5982\u679c\u6709\u4ec0\u4e48\u7591\u95ee\u6216\u8005\u5efa\u8bae\uff0c\u53ef\u4ee5\u5728\u516c\u4f17\u53f7\u4e0b\u591a\u591a\u56de\u590d\u4ea4\u6d41\uff1b\u6587\u4e2d\u82e5\u6709\u4e0d\u6b63\u4e4b\u5904\uff0c\u4e5f\u5e0c\u671b\u56de\u590d\u7559\u8a00\u4ee5\u544a\u77e5\uff01<\/p>\n","protected":false},"excerpt":{"rendered":"
\u5f53\u524d\u4f4d\u7f6e\uff1a > > ...<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4925],"tags":[],"class_list":["post-207748","post","type-post","status-publish","format-standard","hentry","category-4925"],"_links":{"self":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts\/207748","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/comments?post=207748"}],"version-history":[{"count":0,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/posts\/207748\/revisions"}],"wp:attachment":[{"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/media?parent=207748"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/categories?post=207748"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/server.hk\/cnblog\/wp-json\/wp\/v2\/tags?post=207748"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}