oapi-codegen 使用教程

1. 项目目录结构及介绍

oapi-codegen 是一个用于从 OpenAPI 规范生成 Go 代码的工具。以下是项目的目录结构及其简要介绍：

oapi-codegen/
├── cmd/              # 包含 oapi-codegen 命令行工具的实现
│   └── oapi-codegen/  # oapi-codegen 命令行工具的具体代码
├── contrib/          # 社区贡献的插件和工具
├── docs/             # 项目文档
├── examples/         # 使用 oapi-codegen 的示例项目
├── internal/         # 内部测试和工具代码
├── pkg/              # 核心库代码，包含生成 Go 代码的逻辑
├── test/             # 单元测试和集成测试代码
├── configuration-schema.json # 配置文件的 JSON Schema，用于 IDE 的智能提示
├── go.mod            # Go 依赖管理文件
├── go.sum            # Go 依赖校验文件
└── README.md         # 项目自述文件

2. 项目的启动文件介绍

oapi-codegen 的启动文件位于 cmd/oapi-codegen/main.go。以下是启动文件的主要内容：

package main

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

func main() {
    codegen.Generate(os.Args[1:])
}

这个文件非常简洁，它导入了 oapi-codegen 的核心库 codegen，并在 main 函数中调用 Generate 函数，该函数负责处理命令行参数并生成代码。

3. 项目的配置文件介绍

oapi-codegen 使用 YAML 格式的配置文件来简化命令行参数的使用。配置文件的示例可能如下所示：

package: example

templates:
  - path: templates/{{.ServerPackage}}/server.go.tmpl
    dst: paths/{{.ServerPackage}}/server.go
  - path: templates/{{.ServerPackage}}/api.go.tmpl
    dst: paths/{{.ServerPackage}}/api.go
  - path: templates/{{.ServerPackage}}/doc.go.tmpl
    dst: paths/{{.ServerPackage}}/doc.go
  - path: templates/{{.ClientPackage}}/client.go.tmpl
    dst: paths/{{.ClientPackage}}/client.go

paths:
  ServerPackage: example/server
  ClientPackage: example/client

schema:
  file: openapi.yaml

配置文件定义了以下内容：

• package: 生成的 Go 代码的包名。
• templates: 模板文件列表，指定了模板的路径和生成文件的输出路径。
• paths: 包含了生成代码的包路径和其他相关路径。
• schema: 指定了 OpenAPI 规范文件的路径。

这个配置文件告诉 oapi-codegen 如何根据提供的 OpenAPI 规范生成 Go 代码，并将生成的代码放在指定的位置。