Cowboy Swagger 项目教程

Cowboy Swagger 项目教程

cowboy_swagger Swagger integration for Cowboy (built on trails) 项目地址: https://gitcode.com/gh_mirrors/co/cowboy_swagger

1. 项目的目录结构及介绍

Cowboy Swagger 项目的目录结构如下：

cowboy_swagger/
├── CHANGELOG.md
├── LICENSE
├── README.md
├── SWAGGER_VSN
├── elvis_config
├── rebar.config
├── rebar.lock
├── github/
│   └── workflows/
│       └── example
├── priv/
│   └── swagger/
├── src/
│   ├── cowboy_swagger_handler.erl
│   └── ...
├── test/
│   └── ...
└── ...

目录结构介绍

• CHANGELOG.md: 记录项目的变更日志。
• LICENSE: 项目的开源许可证文件。
• README.md: 项目的介绍和使用说明。
• SWAGGER_VSN: 记录 Swagger 的版本信息。
• elvis_config: Elvis 代码风格检查工具的配置文件。
• rebar.config: Rebar3 构建工具的配置文件。
• rebar.lock: Rebar3 锁定依赖版本的文件。
• github/workflows/example: GitHub Actions 的工作流示例。
• priv/swagger: 存放 Swagger UI 的静态文件。
• src: 存放项目的源代码文件，包括 cowboy_swagger_handler.erl 等。
• test: 存放项目的测试代码文件。

2. 项目的启动文件介绍

Cowboy Swagger 项目的启动文件主要包括 src/cowboy_swagger_handler.erl 和 src/example_echo_handler.erl 等。

src/cowboy_swagger_handler.erl

该文件是 Cowboy Swagger 的核心处理模块，负责将 Swagger 文档集成到 Cowboy 服务器中。它实现了 trails_handler:trails/0 回调函数，用于定义 API 的路由和元数据。

src/example_echo_handler.erl

该文件是一个示例处理模块，展示了如何使用 Cowboy Swagger 来文档化 Cowboy 的 RESTful API。它同样实现了 trails_handler:trails/0 回调函数，并定义了 API 的元数据。

3. 项目的配置文件介绍

Cowboy Swagger 项目的配置文件主要包括 rebar.config 和 app.config。

rebar.config

该文件是 Rebar3 构建工具的配置文件，定义了项目的依赖、编译选项等。

{deps, [
    {cowboy, "2.10.0"},
    {jsx, "3.1.0"},
    {trails, "2.3.1"}
]}.

app.config

该文件是 Erlang 应用程序的配置文件，定义了 Cowboy Swagger 的全局配置。

[
    {cowboy_swagger, [
        {static_files, "priv/swagger"},
        {global_spec, #{
            swagger => "2.0",
            info => #{title => "Example API"},
            basePath => "/api-docs"
        }}
    ]}
].

配置项介绍

• static_files: 指定 Swagger UI 静态文件的目录路径。
• global_spec: 定义 Swagger 规范的全局字段，如 swagger 版本、API 标题和基础路径等。

通过以上配置，Cowboy Swagger 可以生成并展示 API 的 Swagger 文档，方便开发者查看和测试 API。

cowboy_swagger Swagger integration for Cowboy (built on trails) 项目地址: https://gitcode.com/gh_mirrors/co/cowboy_swagger