如何从Go源代码生成OpenAPI v3规范？

亲爱的编程学习爱好者，如果你点开了这篇文章，说明你对《如何从Go源代码生成OpenAPI v3规范？》很感兴趣。本篇文章就来给大家详细解析一下，主要介绍一下，希望所有认真读完的童鞋们，都有实质性的提高。

有没有办法从go源代码生成openapi v3规范？假设我可以尝试一下 像下面这样的 api，我想从中生成 openapi 规范（yaml 文件）。类似于python的flask restx。我知道有一些工具可以根据规范生成 go 源代码，但是，我想以相反的方式进行操作。

package main

import "net/http"

func main() {
    http.HandleFunc("/hello", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("world\n"))
    })
    http.ListenAndServe(":5050", nil)
}

解决方案

您可以使用 github.com/swaggest/rest 构建自记录 http rest api。该库建立了一个约定，以可用于反映文档和模式并维护有关它的单一事实来源的方式声明处理程序。

我个人认为，与规范优先方法相比，代码优先方法具有优势。它不需要成为规范语言语法方面的专家，因此可以降低入门门槛。它可能有助于提出一个与实现细节很好平衡的规范。

使用代码优先方法，无需实现完整的服务来获取规范。您只需要定义结构和接口，可以推迟实际的逻辑实现。

请查看简单使用example。

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "time"

    "github.com/go-chi/chi"
    "github.com/go-chi/chi/middleware"
    "github.com/swaggest/rest"
    "github.com/swaggest/rest/chirouter"
    "github.com/swaggest/rest/jsonschema"
    "github.com/swaggest/rest/nethttp"
    "github.com/swaggest/rest/openapi"
    "github.com/swaggest/rest/request"
    "github.com/swaggest/rest/response"
    "github.com/swaggest/rest/response/gzip"
    "github.com/swaggest/swgui/v3cdn"
    "github.com/swaggest/usecase"
    "github.com/swaggest/usecase/status"
)

func main() {
    // init api documentation schema.
    apischema := &openapi.collector{}
    apischema.reflector().specens().info.title = "basic example"
    apischema.reflector().specens().info.withdescription("this app showcases a trivial rest api.")
    apischema.reflector().specens().info.version = "v1.2.3"

    // setup request decoder and validator.
    validatorfactory := jsonschema.newfactory(apischema, apischema)
    decoderfactory := request.newdecoderfactory()
    decoderfactory.applydefaults = true
    decoderfactory.setdecoderfunc(rest.paraminpath, chirouter.pathtourlvalues)

    // create router.
    r := chirouter.newwrapper(chi.newrouter())

    // setup middlewares.
    r.use(
        middleware.recoverer,                          // panic recovery.
        nethttp.openapimiddleware(apischema),          // documentation collector.
        request.decodermiddleware(decoderfactory),     // request decoder setup.
        request.validatormiddleware(validatorfactory), // request validator setup.
        response.encodermiddleware,                    // response encoder setup.
        gzip.middleware,                               // response compression with support for direct gzip pass through.
    )

    // create use case interactor.
    u := usecase.iointeractor{}

    // describe use case interactor.
    u.settitle("greeter")
    u.setdescription("greeter greets you.")

    // declare input port type.
    type helloinput struct {
        locale string `query:"locale" default:"en-us" pattern:"^[a-z]{2}-[a-z]{2}$" enum:"ru-ru,en-us"`
        name   string `path:"name" minlength:"3"` // field tags define parameter location and json schema constraints.
    }
    u.input = new(helloinput)

    // declare output port type.
    type hellooutput struct {
        now     time.time `header:"x-now" json:"-"`
        message string    `json:"message"`
    }
    u.output = new(hellooutput)

    u.setexpectederrors(status.invalidargument)
    messages := map[string]string{
        "en-us": "hello, %s!",
        "ru-ru": "Привет, %s!",
    }
    u.interactor = usecase.interact(func(ctx context.context, input, output interface{}) error {
        var (
            in  = input.(*helloinput)
            out = output.(*hellooutput)
        )

        msg, available := messages[in.locale]
        if !available {
            return status.wrap(errors.new("unknown locale"), status.invalidargument)
        }

        out.message = fmt.sprintf(msg, in.name)
        out.now = time.now()

        return nil
    })

    // add use case handler to router.
    r.method(http.methodget, "/hello/{name}", nethttp.newhandler(u))

    // swagger ui endpoint at /docs.
    r.method(http.methodget, "/docs/openapi.json", apischema)
    r.mount("/docs", v3cdn.newhandler(apischema.reflector().spec.info.title,
        "/docs/openapi.json", "/docs"))

    // start server.
    log.println("http://localhost:8011/docs")
    if err := http.listenandserve(":8011", r); err != nil {
        log.fatal(err)
    }
}

您可以使用 Huma（完全公开：我是作者）从 go 代码生成 openapi 3.1 和 json schema，它适用于各种流行的路由器，因此可以根据需要集成到现有代码库中。 huma 利用 go 泛型为输入参数、主体、响应头等提供编译时检查。

这是一个简单的 hello world 示例，只有几行：

package main

import (
    "context"
    "fmt"
    "net/http"

    "github.com/danielgtaylor/huma/v2"
    "github.com/danielgtaylor/huma/v2/adapters/humachi"
    "github.com/go-chi/chi/v5"
)

// greetinginput represents the greeting operation request.
type greetinginput struct {
    name string `path:"name" maxlength:"30" example:"world" doc:"name to greet"`
}

// greetingoutput represents the greeting operation response.
type greetingoutput struct {
    body struct {
        message string `json:"message" example:"hello, world!" doc:"greeting message"`
    }
}

func main() {
    // create a new router & api
    router := chi.newmux()
    api := humachi.new(router, huma.defaultconfig("my api", "1.0.0"))

    // register get /greeting/{name}
    huma.register(api, huma.operation{
        operationid: "get-greeting",
        summary:     "get a greeting",
        method:      http.methodget,
        path:        "/greeting/{name}",
    }, func(ctx context.context, input *greetinginput) (*greetingoutput, error) {
        resp := &greetingoutput{}
        resp.body.message = fmt.sprintf("hello, %s!", input.name)
        return resp, nil
    })

    // start the server!
    http.listenandserve("127.0.0.1:8888", router)
}

然后您可以轻松地从服务获取生成的 openapi：

curl http://localhost:8888/openapi.json

您还可以在 http://localhost:8888/docs 查看 openapi 生成的文档。

今天关于《如何从Go源代码生成OpenAPI v3规范？》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！