Open API Spex 使用教程

Open API Spex 使用教程

open_api_spexOpen API Specifications for Elixir Plug applications项目地址:https://gitcode.com/gh_mirrors/op/open_api_spex

项目介绍

Open API Spex 是一个用于 Elixir Plug 应用程序的 Open API 规范工具。它允许开发者定义和验证 API 的请求和响应，确保 API 文档的准确性和可靠性。通过集成 Swagger UI，开发者可以交互式地探索和测试 API。

项目快速启动

安装

首先，将 open_api_spex 添加到你的 mix.exs 文件的依赖列表中：

def deps do
  [
    {:open_api_spex, "~> 3.20"}
  ]
end

然后运行 mix deps.get 来安装依赖。

生成规范

在你的应用程序中添加一个 ApiSpec 模块来定义 Open API 规范：

defmodule MyAppWeb.ApiSpec do
  alias OpenApiSpex.{Components, Info, OpenApi, Paths, Server}
  alias MyAppWeb.{Endpoint, Router}

  @behaviour OpenApi

  @impl OpenApi
  def spec do
    %OpenApi{
      info: %Info{
        title: "MyApp API",
        version: "1.0"
      },
      servers: [
        %Server{
          url: "http://localhost:4000"
        }
      ],
      paths: Paths.from_router(Router)
    }
    |> OpenApiSpex.resolve_schema_modules()
  end
end

配置路由

在你的路由文件中配置 Swagger UI 和 API 规范的访问路径：

defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  pipeline :api do
    plug :accepts, ["json"]
  end

  scope "/" do
    pipe_through :api

    get "/swaggerui", OpenApiSpex.Plug.SwaggerUI, path: "/api/openapi"
  end

  scope "/api" do
    pipe_through :api

    get "/openapi", OpenApiSpex.Plug.RenderSpec, []
  end
end

启动应用

在开发环境中，为了确保生成的规范文件被刷新，你应该禁用缓存：

# config/dev.exs
config :open_api_spex, :cache_adapter, OpenApiSpex.Plug.NoneCache

应用案例和最佳实践

验证请求参数

Open API Spex 可以自动验证请求参数，确保它们符合定义的规范：

defmodule MyAppWeb.UserController do
  use MyAppWeb, :controller

  alias MyAppWeb.Schemas.User

  plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true

  def create(conn, params) do
    # 处理创建用户的逻辑
  end
end

验证响应

在测试中验证响应是否符合规范：

defmodule MyAppWeb.UserControllerTest do
  use MyAppWeb.ConnCase

  test "create user", %{conn: conn} do
    params = %{
      "user" => %{
        "name" => "John Doe",
        "email" => "john.doe@example.com"
      }
    }

    conn = post(conn, "/api/users", params)
    assert json_response(conn, 201)["data"]["name"] == "John Doe"
  end
end

典型生态项目

Swagger UI

Swagger UI 是一个交互式的 API 文档工具，可以通过 Open API Spex 集成到你的 Elixir 应用中，方便开发者查看和测试 API。

Phoenix

Phoenix 是一个 Elixir 的 Web 框架，与 Open API Spex 结合使用，可以快速开发和验证 RESTful API。

通过以上步骤，你可以快速启动并使用 Open API Spex 来定义、验证和文档化你的 Elixir 应用程序的 API。

open_api_spexOpen API Specifications for Elixir Plug applications项目地址:https://gitcode.com/gh_mirrors/op/open_api_spex