GO 的 Web 开发系列—— 使用 Swagger 生成一份好看的接口文档

package main
 
import (
    "net/http"
 
    "github.com/getkin/kin-openapi/openapi3"
    "github.com/getkin/kin-openapi/openapi3gen"
    "github.com/go-openapi/inflect"
    "github.com/go-openapi/strfmt"
)
 
// 定义一个简单的API结构
type API struct {
    spec *openapi3.T
}
 
// 初始化API并生成OpenAPI 3.0规范
func NewAPI() (*API, error) {
    // 创建OpenAPI对象
    api := openapi3.NewSwagger()
 
    // 设置服务信息
    api.Info = &openapi3.Info{
        Title:       "示例API",
        Description: "这是一个使用Go和OpenAPI 3.0生成的API文档示例",
        Version:     "v1.0.0",
    }
 
    // 设置服务器地址
    api.Servers = openapi3.Servers{
        {
            URL: "https://example.com/api",
        },
    }
 
    // 生成路径项
    pathItem := openapi3.NewPathItem()
 
    // 添加操作
    res := openapi3.NewResponse()
    res.Description = "成功返回示例"
    pathItem.Get.Description = "获取示例数据"
    pathItem.Get.Responses = map[string]*openapi3.Response{
        "200": res,
    }
 
    // 将路径项添加到API规范
    api.Paths["/example"] = pathItem
 
    // 生成OpenAPI规范
    returnedSpec, err := openapi3gen.GenerateSpec(api, strfmt.Default)
    if err != nil {
        return nil, err
    }
 
    return &API{spec: returnedSpec}, nil
}
 
// 注册API到HTTP服务
func (a *API) RegisterRoutes(mux *http.ServeMux) {
    docs, err := openapi3.NewSwaggerUIHandler(a.spec)
    if err != nil {
        panic(err)
    }
 
    mux.Handle("/docs/", http.StripPrefix("/docs/", docs))
}
 
func main() {
    api, err := NewAPI()
    if err != nil {
        panic(err)
    }
 
    mux := http.NewServeMux()
    api.RegisterRoutes(mux)
 
    http.ListenAndServe(":8080", mux)
}

这段代码首先导入了必要的包，然后定义了一个API结构体，用于存储生成的OpenAPI规范。NewAPI 函数初始化了一个OpenAPI对象，并设置了基本的服务信息和服务器地址，然后为API添加了一个路径项和相应的操作。最后，它生成了OpenAPI规范并返回了一个API实例。RegisterRoutes 方法注册了Swagger UI提供的文档处理器，使得用户可以通过浏览器访问API文档。最后，在main函数中，我们创建了一个API实例，注册了路由，并启动了一个HTTP服务器监听8080端口。