oapi-codegen 项目教程

oapi-codegen 项目教程

oapi-codegen Generate Go client and server boilerplate from OpenAPI 3 specifications 项目地址: https://gitcode.com/gh_mirrors/oap/oapi-codegen

1. 项目目录结构及介绍

oapi-codegen 是一个用于将 OpenAPI 规范转换为 Go 代码的命令行工具和库。以下是项目的目录结构及其介绍：

oapi-codegen/
├── cmd/
│   └── oapi-codegen/
│       └── main.go  # 主程序入口
├── examples/       # 示例代码
├── internal/
│   └── test/       # 内部测试代码
├── pkg/            # 核心库代码
│   ├── chi-middleware/
│   ├── codegen/
│   ├── ecdsafile/
│   ├── fiber-middleware/
│   ├── gin-middleware/
│   ├── iris-middleware/
│   ├── middleware/
│   ├── runtime/
│   ├── securityprovider/
│   ├── testutil/
│   ├── types/
│   └── util/
├── .editorconfig   # 编辑器配置文件
├── .gitattributes  # Git 属性配置
├── .gitignore      # Git 忽略文件配置
├── CONTRIBUTING.md # 贡献指南
├── LICENSE         # 许可证文件
├── Makefile        # Makefile 文件
├── README.md       # 项目介绍文档
├── configuration-schema.json # 配置文件模式
├── go.mod          # Go 模块文件
├── go.sum          # Go 模块校验文件
└── renovate.json   # Renovate 配置文件

目录介绍

• cmd/: 包含主程序的入口文件。
• examples/: 包含项目的示例代码，展示了如何使用 oapi-codegen 生成 Go 代码。
• internal/test/: 包含项目的内部测试代码。
• pkg/: 包含项目的核心库代码，包括各种中间件和工具函数。
• .editorconfig: 编辑器配置文件，用于统一代码风格。
• .gitattributes: Git 属性配置文件。
• .gitignore: Git 忽略文件配置。
• CONTRIBUTING.md: 贡献指南，指导开发者如何为项目贡献代码。
• LICENSE: 项目许可证文件。
• Makefile: Makefile 文件，包含项目的构建和测试命令。
• README.md: 项目介绍文档，包含项目的使用说明和示例。
• configuration-schema.json: 配置文件模式，定义了配置文件的结构。
• go.mod: Go 模块文件，定义了项目的依赖。
• go.sum: Go 模块校验文件，用于校验依赖的完整性。
• renovate.json: Renovate 配置文件，用于自动更新依赖。

2. 项目的启动文件介绍

项目的启动文件位于 cmd/oapi-codegen/main.go。该文件是 oapi-codegen 命令行工具的入口点。以下是 main.go 文件的简要介绍：

package main

import (
    "github.com/oapi-codegen/oapi-codegen/pkg/codegen"
    "github.com/oapi-codegen/oapi-codegen/pkg/util"
    "os"
)

func main() {
    // 解析命令行参数
    args := util.ParseArgs()

    // 生成代码
    err := codegen.GenerateCode(args)
    if err != nil {
        os.Exit(1)
    }
}

启动文件功能

• 解析命令行参数: 使用 util.ParseArgs() 函数解析命令行参数，获取用户输入的配置。
• 生成代码: 调用 codegen.GenerateCode(args) 函数，根据用户输入的配置生成 Go 代码。

3. 项目的配置文件介绍

oapi-codegen 支持通过配置文件来定制代码生成的行为。配置文件通常是一个 YAML 文件，以下是一个示例配置文件的内容及其介绍：

# yaml-language-server: $schema=https://raw.githubusercontent.com/deepmap/oapi-codegen/HEAD/configuration-schema.json
package: api
output: gen/go
generate:
  models: true
  server: true
  client: true
output-options:
  include-tags: []
  exclude-tags: []
  include-operation-ids: []
  exclude-operation-ids: []
  exclude-schemas: []

配置文件字段介绍

• package: 生成的 Go 代码的包名。
• output: 生成的 Go 代码的输出目录。
• generate: 指定要生成的代码类型，包括 models（模型）、server（服务器）和 client（客户端）。
• output-options: 输出选项，包括标签和操作 ID 的包含和排除规则，以及要排除的 schema。

通过配置文件，用户可以灵活地定制 oapi-codegen 生成的代码，以满足不同的需求。

oapi-codegen Generate Go client and server boilerplate from OpenAPI 3 specifications 项目地址: https://gitcode.com/gh_mirrors/oap/oapi-codegen