Skip to main content

Swagger 文档

Swagger文档

Swagger文档主要基于openapi v3版本生成，通过在 proto 里定义 option， 然后通过google开源的 gnostic 来生成。

文档定义#

基本信息的定义#

可以定义的基本信息包含

  • 标题
  • 版本
  • 描述
  • 联系人的姓名，Email
  • 服务的环境名称及对应的接口地址
  • 认证的方式, 比如JWT

举例如下

syntax = "proto3";
package api.micro.user.v1;
import "google/api/annotations.proto";import "gogo/protobuf/gogo.proto";import "openapiv3/annotations.proto";
option go_package = "github.com/go-microservice/ins-api/api/micro/user/v1;v1";
// 文档基本信息定义option (openapi.v3.document) = {  info: {    title: "ins-api";    version: "v1.0.0";    description: "Description from annotation";    contact: {      name: "Contact Name";      url: "https://github.com/go-microservice/ins-api";      email: "";    }    license: {      name: "MIT License";      url: "https://github.com/go-microservice/ins-api/blob/main/LICENSE";    }  }  servers: [    {      url: "http://localhost:8081";      description: "测试环境";    },    {      url: "http://api.go-microservice.io";      description: "线上环境";    }  ]  components: {    security_schemes: {      additional_properties: [        {          name: "bearerAuth";          value: {            security_scheme: {              type: "http";              scheme: "bearer";              bearer_format: "JWT";            }          }        }      ]    }  }  security: [    {      additional_properties: [        {          name: "bearerAuth";          value: {            value: []          }        }      ]    }  ]};

效果如下

swagger-doc-demo

为service和message增加注释#

如果想让service、method及字段在文档里都有比较清晰的说明，可以在对应proto的地方加上详细的注释，示例

syntax = "proto3";
package api.micro.moment.v1;
import "google/api/annotations.proto";import "api/micro/user/v1/user.proto";import "gogo/protobuf/gogo.proto";import "openapiv3/annotations.proto";
option go_package = "github.com/go-microservice/ins-api/api/micro/moment/v1;v1";option java_multiple_files = true;option java_package = "api.micro.moment.v1";
// 评论接口service CommentService {    // 创建评论    rpc CreateComment (CreateCommentRequest) returns (CreateCommentReply) {        option (google.api.http) = {            post: "/v1/comments"            body: "*"        };    };}
// 评论结构message Comment {    // 评论id    string id = 1 [(gogoproto.jsontag) = "id"];    // 帖子id    int64 post_id = 2 [(gogoproto.jsontag) = "post_id"];    // 用户信息    api.micro.user.v1.User user = 3 [(gogoproto.jsontag) = "user"];    // 评论内容    string content = 4 [(gogoproto.jsontag) = "content"];    // 根评论id    int64 root_id = 5 [(gogoproto.jsontag) = "root_id"];    // 父评论id    int64 parent_id = 6 [(gogoproto.jsontag) = "parent_id"];    // 点赞数    int32 like_count = 7 [(gogoproto.jsontag) = "like_count"];    // 回复数    int32 reply_count = 8 [(gogoproto.jsontag) = "reply_count"];    // 分数    int64 score = 9 [(gogoproto.jsontag) = "score"];    // 删除标记    int32 del_flag = 10 [(gogoproto.jsontag) = "del_flag"];    // 创建时间    int64 created_at = 11 [(gogoproto.jsontag) = "created_at"];    // 更新时间    int64 updated_at = 12 [(gogoproto.jsontag) = "updated_at"];    // 设备类型 iOS/Android    string device_type = 13 [(gogoproto.jsontag) = "device_type"];    // 用户id    string ip = 14 [(gogoproto.jsontag) = "ip"];}
message CreateCommentRequest {    // 帖子id    int64 post_id = 1;    // 发布评论的uid    int64 user_id = 2;    // 评论的具体内容    string content = 3;    // 评论的根id    int64 root_id = 4;    // 评论的上一级id    int64 parent_id = 5;    // 设备类型，比如iOS, Android    string device_type = 6;    // 评论人的ip地址    string ip = 7;}message CreateCommentReply {    Comment comment = 1;}

使用脚本生成文档#

通过下面的命令可以生成一个文件：openapi.yaml，位于根目录的docs目录下， 然后通过对应的js和css进行渲染。

make grpcmake openapi

最后开启web server后即可进行访问，访问地址：http://localhost:8081/docs

Reference#