Open API Spex完全指南Elixir Plug应用的终极API规范工具【免费下载链接】open_api_spexOpen API Specifications for Elixir Plug applications项目地址: https://gitcode.com/gh_mirrors/op/open_api_spexOpen API Spex是Elixir Plug应用的终极API规范工具它能帮助开发者轻松实现API文档化、测试、验证和交互式探索。本文将全面介绍如何使用Open API Spex为Elixir Plug应用构建专业的Open API规范从安装配置到高级功能让你的API开发效率提升10倍为什么选择Open API SpexOpen API Spex为Elixir开发者提供了完整的Open API 3规范支持主要优势包括自动生成API文档从代码中提取规范保持文档与实现同步请求验证在请求到达控制器前自动验证参数减少错误处理代码响应测试确保API响应符合规范提高文档可靠性交互式探索集成SwaggerUI让API测试变得简单直观无论是小型项目还是大型企业应用Open API Spex都能帮助你构建更加规范、可靠的API服务。快速安装步骤安装Open API Spex非常简单只需在mix.exs文件中添加依赖def deps do [ {:open_api_spex, ~ 3.21} ] end然后运行mix deps.get安装依赖。对于需要YAML格式输出的项目还需添加ymlr依赖def deps do [ {:open_api_spex, ~ 3.21}, {:ymlr, ~ 2.0} ] end生成API规范的核心步骤创建主规范模块首先创建一个ApiSpec模块来定义API的基本信息和服务器配置defmodule MyAppWeb.ApiSpec do alias OpenApiSpex.{Components, Info, OpenApi, Paths, Server} alias MyAppWeb.{Endpoint, Router} behaviour OpenApi impl OpenApi def spec do %OpenApi{ servers: [ Server.from_endpoint(Endpoint) ], info: %Info{ title: My App, version: 1.0 }, paths: Paths.from_router(Router) } | OpenApiSpex.resolve_schema_modules() end end你还可以从应用配置中动态获取标题和版本info: %Info{ title: to_string(Application.spec(:my_app, :description)), version: to_string(Application.spec(:my_app, :vsn)) }定义API操作在控制器中使用OpenApiSpex.ControllerSpecs定义API操作defmodule MyAppWeb.UserController do use MyAppWeb, :controller use OpenApiSpex.ControllerSpecs alias MyAppWeb.Schemas.{UserParams, UserResponse} tags [users] operation :update, summary: Update user, parameters: [ id: [in: :path, description: User ID, type: :integer, example: 1001] ], request_body: {User params, application/json, UserParams}, responses: [ ok: {User response, application/json, UserResponse} ] def update(conn, %{id id}) do # 控制器逻辑 end end定义数据模型使用OpenApiSpex.schema/1宏定义请求和响应的数据模型defmodule MyAppWeb.Schemas.User do require OpenApiSpex OpenApiSpex.schema(%{ title: User, description: A user of the app, type: :object, properties: %{ id: %Schema{type: :integer, description: User ID}, name: %Schema{type: :string, description: User name}, email: %Schema{type: :string, description: Email address, format: :email} }, required: [:name, :email], example: %{ id 123, name Joe User, email joegmail.com } }) end服务API规范文档配置路由在router.ex中添加路由以提供API规范pipeline :api do plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec end scope /api do pipe_through :api get /openapi, OpenApiSpex.Plug.RenderSpec, [] end生成静态规范文件使用Mix任务生成JSON或YAML格式的规范文件mix openapi.spec.json --spec MyAppWeb.ApiSpec mix openapi.spec.yaml --spec MyAppWeb.ApiSpec集成SwaggerUI添加SwaggerUI路由让用户可以交互式地探索APIscope / do pipe_through :browser get /swaggerui, OpenApiSpex.Plug.SwaggerUI, path: /api/openapi end现在访问/swaggerui即可看到交互式API文档用户可以直接在界面上测试API端点。请求验证与参数转换Open API Spex可以自动验证请求并将参数转换为指定类型只需在控制器中添加插件defmodule MyAppWeb.UserController do use MyAppWeb, :controller use OpenApiSpex.ControllerSpecs plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true # 操作定义和控制器逻辑... end启用后不符合规范的请求将自动返回422错误并包含详细的验证信息{ errors: [ { detail: Invalid format. Expected :date, source: { pointer: /data/birthday }, title: Invalid value } ] }测试API响应使用OpenApiSpex.TestAssertions模块验证API响应是否符合规范use MyAppWeb.ConnCase import OpenApiSpex.TestAssertions test UserController produces a valid response, %{conn: conn} do json conn | get(user_path(conn, :index)) | json_response(200) api_spec MyAppWeb.ApiSpec.spec() assert_schema(json, UsersResponse, api_spec) end高级功能与最佳实践处理认证授权添加安全方案到API规范components: %Components{ securitySchemes: %{authorization %SecurityScheme{type: http, scheme: bearer}} }然后在操作中应用安全要求security: [%{authorization []}]自定义错误响应创建自定义错误渲染器以返回特定格式的错误响应plug OpenApiSpex.Plug.CastAndValidate, render_error: MyErrorRendererPlug导入现有规范如果已有JSON或YAML格式的Open API规范可以直接导入# 导入JSON规范 open_api_spec spec.json | File.read!() | Jason.decode!() | OpenApiSpex.OpenApi.Decode.decode()总结Open API Spex是Elixir Plug应用构建API的瑞士军刀它不仅能帮助你生成专业的API文档还能通过请求验证和响应测试提高API质量。通过本文介绍的步骤你可以快速上手Open API Spex并将其集成到你的Elixir项目中。无论是小型个人项目还是大型企业应用Open API Spex都能为你的API开发流程带来显著提升。立即尝试体验API开发的全新方式要开始使用Open API Spex请克隆仓库git clone https://gitcode.com/gh_mirrors/op/open_api_spex更多详细信息请参考项目中的README.md和示例代码。【免费下载链接】open_api_spexOpen API Specifications for Elixir Plug applications项目地址: https://gitcode.com/gh_mirrors/op/open_api_spex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Open API Spex完全指南：Elixir Plug应用的终极API规范工具
发布时间：2026/6/12 6:24:07
Open API Spex完全指南Elixir Plug应用的终极API规范工具【免费下载链接】open_api_spexOpen API Specifications for Elixir Plug applications项目地址: https://gitcode.com/gh_mirrors/op/open_api_spexOpen API Spex是Elixir Plug应用的终极API规范工具它能帮助开发者轻松实现API文档化、测试、验证和交互式探索。本文将全面介绍如何使用Open API Spex为Elixir Plug应用构建专业的Open API规范从安装配置到高级功能让你的API开发效率提升10倍为什么选择Open API SpexOpen API Spex为Elixir开发者提供了完整的Open API 3规范支持主要优势包括自动生成API文档从代码中提取规范保持文档与实现同步请求验证在请求到达控制器前自动验证参数减少错误处理代码响应测试确保API响应符合规范提高文档可靠性交互式探索集成SwaggerUI让API测试变得简单直观无论是小型项目还是大型企业应用Open API Spex都能帮助你构建更加规范、可靠的API服务。快速安装步骤安装Open API Spex非常简单只需在mix.exs文件中添加依赖def deps do [ {:open_api_spex, ~ 3.21} ] end然后运行mix deps.get安装依赖。对于需要YAML格式输出的项目还需添加ymlr依赖def deps do [ {:open_api_spex, ~ 3.21}, {:ymlr, ~ 2.0} ] end生成API规范的核心步骤创建主规范模块首先创建一个ApiSpec模块来定义API的基本信息和服务器配置defmodule MyAppWeb.ApiSpec do alias OpenApiSpex.{Components, Info, OpenApi, Paths, Server} alias MyAppWeb.{Endpoint, Router} behaviour OpenApi impl OpenApi def spec do %OpenApi{ servers: [ Server.from_endpoint(Endpoint) ], info: %Info{ title: My App, version: 1.0 }, paths: Paths.from_router(Router) } | OpenApiSpex.resolve_schema_modules() end end你还可以从应用配置中动态获取标题和版本info: %Info{ title: to_string(Application.spec(:my_app, :description)), version: to_string(Application.spec(:my_app, :vsn)) }定义API操作在控制器中使用OpenApiSpex.ControllerSpecs定义API操作defmodule MyAppWeb.UserController do use MyAppWeb, :controller use OpenApiSpex.ControllerSpecs alias MyAppWeb.Schemas.{UserParams, UserResponse} tags [users] operation :update, summary: Update user, parameters: [ id: [in: :path, description: User ID, type: :integer, example: 1001] ], request_body: {User params, application/json, UserParams}, responses: [ ok: {User response, application/json, UserResponse} ] def update(conn, %{id id}) do # 控制器逻辑 end end定义数据模型使用OpenApiSpex.schema/1宏定义请求和响应的数据模型defmodule MyAppWeb.Schemas.User do require OpenApiSpex OpenApiSpex.schema(%{ title: User, description: A user of the app, type: :object, properties: %{ id: %Schema{type: :integer, description: User ID}, name: %Schema{type: :string, description: User name}, email: %Schema{type: :string, description: Email address, format: :email} }, required: [:name, :email], example: %{ id 123, name Joe User, email joegmail.com } }) end服务API规范文档配置路由在router.ex中添加路由以提供API规范pipeline :api do plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec end scope /api do pipe_through :api get /openapi, OpenApiSpex.Plug.RenderSpec, [] end生成静态规范文件使用Mix任务生成JSON或YAML格式的规范文件mix openapi.spec.json --spec MyAppWeb.ApiSpec mix openapi.spec.yaml --spec MyAppWeb.ApiSpec集成SwaggerUI添加SwaggerUI路由让用户可以交互式地探索APIscope / do pipe_through :browser get /swaggerui, OpenApiSpex.Plug.SwaggerUI, path: /api/openapi end现在访问/swaggerui即可看到交互式API文档用户可以直接在界面上测试API端点。请求验证与参数转换Open API Spex可以自动验证请求并将参数转换为指定类型只需在控制器中添加插件defmodule MyAppWeb.UserController do use MyAppWeb, :controller use OpenApiSpex.ControllerSpecs plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true # 操作定义和控制器逻辑... end启用后不符合规范的请求将自动返回422错误并包含详细的验证信息{ errors: [ { detail: Invalid format. Expected :date, source: { pointer: /data/birthday }, title: Invalid value } ] }测试API响应使用OpenApiSpex.TestAssertions模块验证API响应是否符合规范use MyAppWeb.ConnCase import OpenApiSpex.TestAssertions test UserController produces a valid response, %{conn: conn} do json conn | get(user_path(conn, :index)) | json_response(200) api_spec MyAppWeb.ApiSpec.spec() assert_schema(json, UsersResponse, api_spec) end高级功能与最佳实践处理认证授权添加安全方案到API规范components: %Components{ securitySchemes: %{authorization %SecurityScheme{type: http, scheme: bearer}} }然后在操作中应用安全要求security: [%{authorization []}]自定义错误响应创建自定义错误渲染器以返回特定格式的错误响应plug OpenApiSpex.Plug.CastAndValidate, render_error: MyErrorRendererPlug导入现有规范如果已有JSON或YAML格式的Open API规范可以直接导入# 导入JSON规范 open_api_spec spec.json | File.read!() | Jason.decode!() | OpenApiSpex.OpenApi.Decode.decode()总结Open API Spex是Elixir Plug应用构建API的瑞士军刀它不仅能帮助你生成专业的API文档还能通过请求验证和响应测试提高API质量。通过本文介绍的步骤你可以快速上手Open API Spex并将其集成到你的Elixir项目中。无论是小型个人项目还是大型企业应用Open API Spex都能为你的API开发流程带来显著提升。立即尝试体验API开发的全新方式要开始使用Open API Spex请克隆仓库git clone https://gitcode.com/gh_mirrors/op/open_api_spex更多详细信息请参考项目中的README.md和示例代码。【免费下载链接】open_api_spexOpen API Specifications for Elixir Plug applications项目地址: https://gitcode.com/gh_mirrors/op/open_api_spex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
