如何将swagger ui与golang和goa整合在一起

Question

我一直在使用go和goa构建我的第一个RESTful服务，所以基本上我开始做this，最后，goa会生成两个招摇文件，swagger.yaml和swagger.json。问题是我一直在寻找一种方法来添加swagger ui，比方说，索引。但我无法找到一个例子。

我也会查看examples和design - swagger部分，但他们给我的唯一建议是使用goa swagger design生成器，但我不知道是否有如何在不需要访问公共主机的情况下执行此操作？

Answer 1

TL; DR

files example显示了如何构建一个提供静态资产的API，该API可以适应包含Swager-UI。

为了效仿这个例子：

1. 获取依赖项
2. 将Resource添加到design.go文件
3. 在main.go
中安装控制器
4. 下载并编辑Swagger-UI
5. 运行生成器

在此之后你应该有一个有效的REST-API，包括Swagger-UI

详细

^{（请将example.com/your-package/替换为您的包裹的路径。）}

1。获取依赖项

为了提供文件，该示例使用：

• go-bindata
  ^{从任何文件生成Go代码的小实用程序。用于在Go程序中嵌入二进制数据。}

• go-bindata-assetfs
  ^{使用go-bindata从net/http提供嵌入式文件。}

使用：

go get github.com/a-urth/go-bindata/...
go get github.com/elazarl/go-bindata-assetfs/...

2。将资源添加到design.go文件：

    var _ = Resource("schema", func() {
        Files("/schema/*filepath", "public/schema/")
    })

    var _ = Resource("swagger", func() {
        Files("/swagger/*filepath", "public/swagger/")
    })

3。在main.go

中安装控制器

import (
    "net/http"

    "example.com/your-package/app"
    "example.com/your-package/public/swagger"

    "github.com/elazarl/go-bindata-assetfs"
    "github.com/goadesign/goa"
    "github.com/goadesign/goa/middleware"
)

func main() {
    // ...

    // Mount "schema" controller
    c1 := NewSchemaController(service)
    app.MountSchemaController(service, c1)
    // Mount "swagger" controller
    c2 := NewSwaggerController(service)
    // You can override FileSystem of the controller.
    // For example using github.com/elazarl/go-bindata-assetfs is like below.
    c2.FileSystem = func(dir string) http.FileSystem {
        return &assetfs.AssetFS{
            Asset:     swagger.Asset,
            AssetDir:  swagger.AssetDir,
            AssetInfo: swagger.AssetInfo,
            Prefix:    dir,
        }
    }
    app.MountSwaggerController(service, c2)

    // ...
}

4。下载Swagger-UI

使用your favorite method下载Swagger UI的dist folder。 将所有文件放在example.com/your-package/public/swagger文件夹中。

在example.com/your-package/public/swagger/index.html文件中：

• 搜索http://petstore.swagger.io/v2/swagger.json
• 将其替换为./swagger.json ^{这样生成的swagger.json将被用来代替Petstore示例。}

5。运行生成器

go generate goagen -d example.com/your-package/design app
go generate goagen -d example.com/your-package/design main
go generate goagen -d example.com/your-package/design swagger -o public
go generate goagen -d example.com/your-package/design schema -o public
go generate go-bindata -ignore 'bindata.go' -pkg swagger -o public/swagger/bindata.go ./public/swagger/...

这将创建控制器，swagger，架构和静态内容。

完成

您现在应该拥有功能齐全的Swagger UI。

Answer 2

我最近在运行这个，也想知道如何让 swagger ui 起来。生成 openapi3.json 文件后，您可以使用此 docker-compose 配置来调出 swagger ui。您可以根据文件所在的位置替换安装的卷和 SWAGGER_JSON 变量。 Swagger ui 在 http://localhost:8080 中应该可以正常运行。

注意：您可能需要在 goa 中启用 CORS 才能执行请求。

swagger:
  image: swaggerapi/swagger-ui
  ports:
    - '8080:8080'
  environment:
    SWAGGER_JSON: '/openapi3.json'
  volumes:
    - ./gen/http/openapi3.json:/openapi3.json