Merge pull request #21 from inaka/cabol.1.fulfil_open_source_list

[#1] Fixed documentation in modules. Fixed README.

README.md

@@ -103,5 +103,40 @@ And that's it, you got it. Now start your application and then you will have acc
 under the path `/api-docs`. Supposing that you're running the app on `localhost:8080`,
 that will be [http://localhost:8080/api-docs](http://localhost:8080/api-docs).
 
+## Configuration
+
+Additionally, `cowboy_swagger` can be configured/customized from a `*.config` file:
+
+### app.config
+
+```erlang
+[
+ %% 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"
+     }
+   }
+  ]
+ }
+].
+```
+
 ## Example
 For more information about `cowboy_swagger` and how to use it, please check this [Example](./example).

src/cowboy_swagger.erl

@@ -45,6 +45,9 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% @doc Returns the swagger json specification from given `trails'.
+%%      This function basically takes the metadata from each `trails:trail()'
+%%      (which must be compliant with Swagger specification) and builds the
+%%      required `swagger.json'.
 -spec to_json([trails:trail()]) -> iolist().
 to_json(Trails) ->
   Default = #{swagger => <<"2.0">>, info => #{title => <<"API-DOCS">>}},
@@ -57,10 +60,12 @@ to_json(Trails) ->
 %% Utilities.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+%% @hidden
 -spec enc_json(jiffy:json_value()) -> iolist().
 enc_json(Json) ->
   jiffy:encode(Json, [uescape]).
 
+%% @hidden
 -spec dec_json(iodata()) -> jiffy:json_value().
 dec_json(Data) ->
   try jiffy:decode(Data, [return_maps])
@@ -69,10 +74,12 @@ dec_json(Data) ->
       throw(bad_json)
   end.
 
+%% @hidden
 -spec swagger_paths([trails:trail()]) -> map().
 swagger_paths(Trails) ->
   swagger_paths(Trails, #{}).
 
+%% @hidden
 -spec validate_metadata(trails:metadata()) -> trails:metadata().
 validate_metadata(Metadata) ->
   validate_swagger_map(Metadata).

src/cowboy_swagger_handler.erl

@@ -1,3 +1,6 @@
+%%% @doc Cowboy Swagger Handler. This handler exposes a GET operation
+%%%      to enable that  `swagger.json' can be retrieved from embedded
+%%%      Swagger-UI (located in `priv/swagger' folder).
 -module(cowboy_swagger_handler).
 
 %% Cowboy callbacks
@@ -19,16 +22,19 @@
 %%% Cowboy Callbacks
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+%% @hidden
 -spec init({atom(), atom()}, cowboy_req:req(), state()) ->
   {upgrade, protocol, cowboy_rest}.
 init(_Transport, _Req, _Opts) ->
   {upgrade, protocol, cowboy_rest}.
 
+%% @hidden
 -spec rest_init(cowboy_req:req(), state()) ->
   {ok, cowboy_req:req(), term()}.
 rest_init(Req, _Opts) ->
   {ok, Req, #{}}.
 
+%% @hidden
 -spec content_types_provided(cowboy_req:req(), state()) ->
   {[term()], cowboy_req:req(), state()}.
 content_types_provided(Req, State) ->
@@ -48,6 +54,9 @@ handle_get(Req, State) ->
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 %% @hidden
+%% @doc Implementets `trails_handler:trails/0' callback. This function returns
+%%      trails routes for both: static content (Swagger-UI) and this handler
+%%      that returns the `swagger.json'.
 trails() ->
   StaticFiles = application:get_env(
     cowboy_swagger, static_files, "priv/swagger"),