帮酷LOGO
  • 显示原文与译文双语对照的内容
文章标签:Swagger  trail  INT  Cowboy  整合  
Swagger integration for Cowboy (built on trails)

  • 源代码名称:cowboy_swagger
  • 源代码网址:http://www.github.com/inaka/cowboy_swagger
  • cowboy_swagger源代码文档
  • cowboy_swagger源代码下载
  • Git URL:
    git://www.github.com/inaka/cowboy_swagger.git
  • Git Clone代码到本地:
    git clone http://www.github.com/inaka/cowboy_swagger
  • Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/inaka/cowboy_swagger
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
  • 牛仔 swagger

    用于 Cowboy ( 建立在追踪系统上)的集成。

    联系我们

    在使用这个库时,如果你发现任何收费的Bug 或者有英镑问题的,请在这个 repo ( 。或者请求请求:) 中打开一个问题( ) 。

    要求

    Cowboy Swagger要求在 0.1.0版本之后 Erlang 18 +

    为什么 Cowboy Swagger?

    简单,因为在Erlang中没有一个工具可以以简单快捷地记录 Cowboy RESTful api,并提高开发效率。

    使用 cowboy_swagger 可以将Swagger集成到使用 Cowboy 作为web服务器的你的Erlang项目。 它非常容易使用,并且只有一些步骤,你将有一个很好的Web文档,你的RESTful api 。

    要了解关于Swagger的更多信息,请查看这个博客文章。

    如何使用它?

    这是最好的。 非常简单。

    1记录每个 Cowboy 处理程序

    因为 cowboy_swagger 运行在 trails的顶部,所以必须做的第一件事是在跟踪元数据中记录所有处理程序。 记住,每个方法中定义的所有字段都必须符合 Swagger规范

    例如假设你有 example_echo_handler,因此它必须实现 trails_handler 行为的trails/0 回调:

    trails() ->Metadata= #{get=> #{tags=> ["echo"],
     description=>"Gets echo var from the server",
     produces=> ["text/plain"]
     },
     put=> #{tags=> ["echo"],
     description=>"Sets echo var in the server",
     produces=> ["text/plain"],
     parameters=> [
     #{name=> <<"echo">>,
     description=> <<"Echo message">>,
     in=> <<"path">>,
     required=>false,
     type=> <<"string">>}
     ]
     }
     },
     [trails:trail("/message/[:echo]", example_echo_handler, [], Metadata)].

    为了更好地了解你的处理程序应该如何工作,请在这里检查

    2在你的应用程序中包含 cowboy_swagger

    首先,需要在要编译的轨迹列表中包含 cowboy_swagger_handler 模块。

    % Include cowboy_swagger_handler in the trails listTrails=trails:trails([example_echo_handler,
     example_description_handler,
     cowboy_swagger_handler]),% store themtrails:store(Trails),% and then compile themDispatch=trails:single_host_compile(Trails),

    上面的代码Fragment通常是在启动 cowboy 时放置的。 看这里,这里是

    然后将 cowboy_swagger 添加到要在 *.app.src 文件中加载的应用程序列表中。

    {application, example,
     [
     {description, "Cowboy Swagger Basic Example."},
     {vsn, "0.1"},
     {applications,
     [kernel,
     stdlib,
     jsx,
     cowboy,
     trails,
     cowboy_swagger ]},
     {modules, []},
     {mod, {example, []}},
     {registered, []},
     {start_phases, [{start_trails_http, []}]}
     ]
    }.

    就是这样,你知道了。 现在启动应用程序,然后你就可以访问路径 /api-docs 下的API文档。 假设你在 localhost:8080 上运行该应用程序,这将是 http://localhost:8080/api-docs 。

    配置

    此外,cowboy_swagger 还可以从 *.config file: 配置/定制

    app.config

    [
     %% Other apps.. .%% cowboy_swagger config {cowboy_swagger,
     [
     %% `static_files`: Static content directory. This is where Swagger-UI%% is located. Default: `priv/swagger`.%% Remember that Swagger-UI is embedded into `cowboy-swagger` project,%% within `priv/swagger` folder. BUT you have to reference that path,%% and depending on how you're using `cowboy-swagger` it will be different.%% For example, assuming that you want to run your app which has%% `cowboy-swagger` as dependency from the console, `static_files` will be: {static_files, "./deps/cowboy_swagger/priv/swagger"},
     %% `global_spec`: Global fields for Swagger specification.%% If these fields are not set, `cowboy_swagger` will set default values. {global_spec,
     #{swagger=>"2.0",
     info=> #{title=>"Example API"},
     basePath=>"/api-docs" }
     }
     ]
     }
    ].

    定义

    定义可以用于描述参数,响应和安全模式。

    为你的应用程序添加定义,你有 2个选择:

    • definitions 键添加到 cowboy_swagger global_spec 映射中。
    • 通过调用 cowboy_swagger:add_definition/2 并发送定义和属性的名称来添加它们。

    假设你想描述一个只需要和 description 字段的POST 调用,那么你可以像这样做:

    选项 1:

    [.. . % other configurations, { cowboy_swagger, [ { global_spec, #{ swagger=>"2.0", info=> #{title=>"My app API"}
    , definitions=> #{
     "RequestBody"=> #{ "name"=> #{ "type"=>"string", "description"=>"Newspaper name" }
    , "description"=> #{ "type"=>"string", "description"=>"Newspaper description" }
     }
     }
     }
     }
     ]
     }
    ]

    选项 2:

    对于第二个选择,可以以在一个或者多个 start_phases 中直接在处理程序或者任何它的他位置进行操作。

    -spectrails() ->trails:trails().trails() ->DefinitionName= <<"RequestBody">>,
     DefinitionProperties= #{ <<"name">> => #{ type=> <<"string">>
    , description=> <<"Newspaper name">>
     }
    , <<"description">> => #{ type=> <<"string">>
    , description=> <<"Newspaper description">>
     }
     },
     % Add the definitionok=cowboy_swagger:add_definition(DefinitionName, DefinitionProperties),
    . . .

    现在在处理程序回调函数的跟踪中,你可以使用它:

    ...
     RequestBody= #{ name=> <<"request body">>
    , in=>body, description=> <<"request body (as json)">>
    , required=>true% Use the previously created `RequestBody' definition, schema=>cowboy_swagger:schema(<<"RequestBody">>)
     },
     Metadata= #{ get=> #{ tags=> ["newspapers"]
    , description=>"Returns the list of newspapers", produces=> ["application/json"]
     }
    , post=> # { tags=> ["newspapers"]
    , description=>"Creates a new newspaper", consumes=> ["application/json"]
    , produces=> ["application/json"]
    , parameters=> [RequestBody] % and then use that parameter here }
     },
     Path="/newspapers",
     Options= #{path=>Path},
     [trails:trail(Path, newspapers_handler, Options, Metadata)].

    它为你添加了一个好的responseparameter 或者 security 模型,因这里客户端开发人员将知道API所需的参数。

    示例

    有关 cowboy_swagger 以及如何使用它的更多信息,请查看这里示例。



    文章标签:INT  整合  Swagger  trail  Cowboy  

    Copyright © 2011 HelpLib All rights reserved.    知识分享协议 京ICP备05059198号-3  |  如果智培  |  酷兔英语