Kratos OpenAPI Swagger 使用

OpenAPI Swagger 使用

框架可通過兩種方式提供OpenAPI/Swagger的使用：1. 在服務(wù)上提供swagger接口，2. 使用protoc插件生成swagger.json文件。下面介紹這兩種方式。

方式1: 使用插件提供swagger接口

swagger-api插件提供了一系列swagger相關(guān)的API，以及相應(yīng)的UI界面

安裝

首先安裝插件到項(xiàng)目中

go get -u github.com/go-kratos/swagger-api

然后在?internal/server/http.go?的NewHTTPServer中進(jìn)行初始化和注冊，請盡量將這個路由注冊放在最前面，以免匹配不到。

import "github.com/go-kratos/swagger-api/openapiv2"

openAPIhandler := openapiv2.NewHandler()
srv.HandlePrefix("/q/", openAPIhandler)

使用

瀏覽器中訪問服務(wù)的?/q/swagger-ui/?路徑即可打開Swagger UI

方式2: 使用protoc插件生成swagger.json文件

新建項(xiàng)目Makefile中已經(jīng)默認(rèn)集成了生成swagger.json的相關(guān)命令，這里也介紹下具體的使用方式

安裝

首先全局安裝protoc插件

go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2

生成

在項(xiàng)目根目錄直接使用protoc命令，請注意修改命令最后的proto文件路徑為實(shí)際路徑

protoc --proto_path=. \
        --proto_path=./third_party \
        --openapiv2_out . \
        --openapiv2_opt logtostderr=true \
        --openapiv2_opt json_names_for_fields=false \
        api/helloworld/v1/greeter.proto

使用

上面的命令執(zhí)行成功后，將在您的proto文件所在目錄生成相應(yīng)的swagger.json文件。 您可以將其導(dǎo)入任何支持OpenAPI規(guī)范的平臺進(jìn)行瀏覽，例如:

• Swagger UI
• Swagger Editor
• ReDoc
• YApi
• Postman