docs/web/api-document-openapiv3

[giscus[bot]]

docs/web/api-document-openapiv3

本文档介绍了如何在GoFrame框架中使用OpenAPIv3协议来规范接口文档的生成。通过嵌入g.Meta元数据结构体，可以自动生成包含协议标签的接口信息。此外，文中还展示了如何自定义扩展标签和手动完善接口文档。

https://goframe.org/docs/web/api-document-openapiv3

[ninjashixuan]

validation rules 加上max min length 规则就好了，现在只有required 是用上，希望加上这样前端看文档就可以直接写自己的校验规则方便很多。

[gqcn]

可以一起共建哈，其实蛮简单的。如果实在不行也可以提个issue记录下，让社区的小伙伴一起来贡献。

[Starix610]

Schema 对象下的字段如何通过struct tag配置，比如想要配置Schema下的enum这个字段

type XxREq struct {
	Type string `json:"type" dc:"类型" schema:"???"`
}

[gqcn]

我建议通过枚举类型来维护，具体可以阅读相关文档：
https://goframe.org/docs/design/enums
https://goframe.org/docs/cli/gen-enums

[ninjashixuan]

想给 responses.200.content.application/json.schema 添加 ref，以及 data field 添加 ref，这种风格上的改动可以接受吗？。因为其他同事根据openapi 直接生成其他语言的调用代码，这个两个有 ref 会更好。可以的话，我提个 pr。

[lfhy]

您好，我想了解一下这个openapi有办法只暴露指定前缀的接口吗，比如我的服务包含/api/v1/admin和/api/v1/user两个前缀的路由，我只想将/api/v1/user/这个前缀的路由接口生成openapi.json来提供用户访问和请求，但目前我发现生成的openapi.json是包含全部的路由，如果要实现这个效果是只能自己编辑openapi.json进行配置了吗，还是配置文件有方法控制呢？

[lala0257]

你可以新开一个server服务， 设定路由，由该sever生成你想要暴露出去的swagger。

[buexplain]

tags怎么设定多个，达到分层效果?

[lfhy]

用 / 分割

[xiaoyi510]

 "protect-server.api.admin.app.v1.AppListRes": {
        "properties": {
          "code": {
            "format": "int",
            "type": "integer"
          },
          "message": {
            "format": "string",
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/protect-server.api.base.PageRes[protect-server/api/admin/app/v1.AppListItem]",
            "description": ""
          }
        },
        "type": "object"
      }

此处$ref 生成有点问题 swagger UI官方提示报错 说不应该有[] 应该是url encode之后的结果

Errors
Hide
 
Semantic error at components.schemas.protect-server.api.admin.app.v1.AppListRes.properties.data.$ref
$ref values must be RFC3986-compliant percent-encoded URIs
Jump to line 185
Semantic error at components.schemas.protect-server.api.admin.app.v1.AppListRes.properties.data.$ref
$refs must reference a valid location in the document
Jump to line 185
Semantic error at components.schemas.protect-server.api.base.PageRes[protect-server/api/admin/app/v1.AppListItem]
Component names can only contain the characters A-Z a-z 0-9 - . _
Jump to line 188
``