# swagger-api
## Quick Start

在项目中引入openapiv2，支持两种模式：

### 模式一：传统模式（服务下拉选择）

每个服务单独显示，通过下拉框切换

```go
import	swagger_api "git.ikuban.com/server/swagger-api/v2"

// 创建传统模式 Handler
h := swagger_api.NewHandler(nil, false)
// 或者指定服务列表
h := swagger_api.NewHandler([]string{"service1", "service2"}, false)

//将/q/路由放在最前匹配
httpSrv.HandlePrefix("/q/", h)
```

启动应用后，在浏览器中输入 [http://\<ip>:\<port>/q/swagger-ui/](http://ip:port/q/swagger-ui/)，在顶栏右侧选框选取希望查看的服务名。
![select service](/img/swagger.png)

### 模式二：合并模式（所有服务在一个页面）

所有服务合并显示在同一个页面，通过 tags 分组

```go
import	swagger_api "git.ikuban.com/server/swagger-api/v2"

// 创建合并模式 Handler
h := swagger_api.NewMergedHandler(nil, false)
// 或者只合并指定的服务
h := swagger_api.NewMergedHandler([]string{"service1", "service2"}, false)

//将/q/路由放在最前匹配
httpSrv.HandlePrefix("/q/", h)
```

启动应用后，在浏览器中输入 [http://\<ip>:\<port>/q/swagger-ui/](http://ip:port/q/swagger-ui/)，所有服务的接口会自动合并显示。

**参数说明：**
- `servicesList []string`: 指定要显示的服务列表，传 `nil` 则显示所有服务
- `skipError bool`: 是否跳过加载错误的服务

## FAQ
#### 1. 如果启动时顶栏选框未显示可选的服务名，或访问/q/services出现报错，`failed to decompress enc: bad gzipped descriptor: EOF`的报错说明部分依赖的proto文件生成的路径不对导致的，
比如:
- api/basedata/tag/v1/tag.proto
- api/basedata/article/v1/article.proto

当 **api/basedata/article/v1/article.proto** import "api/basedata/tag/v1/tag.proto"时 ，生成的依赖为api/basedata/tag/v1/tag.proto 
但是 tag.proto 生成的tag.pb.go文件中source是tag.proto（漏掉了api/basedata/tag/v1/）导致了依赖未找到

此时需要生成tag.pb.go时kratos proto client api/basedata/tag/v1/tag.proto 补全proto的路径，这样生成的tag.pb.go文件中source就是正确的(api/basedata/tag/v1/tag.proto)

#### 2. 给swagger api添加说明、examples
请参考[a_bit_of_everything](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto)，同时注意需要将[annotations.proto](https://github.com/go-kratos/kratos/blob/main/third_party/protoc-gen-openapiv2/options/annotations.proto)和[openapiv2.proto](https://github.com/go-kratos/kratos/blob/main/third_party/protoc-gen-openapiv2/options/openapiv2.proto)这两个proto文件复制到third_party/protoc-gen-openapiv2/options目录下