Merge pull request #152 from paulo-ferraz-oliveira/feature/minor-main…

…tenance-updates

Maintenance updates

.github/workflows/ci.yml

@@ -1,24 +1,34 @@
 ---
 name: build
-on:
-  push:
-    branches:
-      - master
-  pull_request:
-    branches:
-      - master
+on: [push, pull_request]
 jobs:
   ci:
-    name: Run checks and tests over ${{matrix.otp_vsn}} and ${{matrix.os}}
-    runs-on: ${{matrix.os}}
+    name: Run checks and tests over ${{matrix.otp_vsn}}
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
-        otp_vsn: [23, 24]
-        os: [ubuntu-latest]
+        otp_vsn: ['24', '25', '26']
+        rebar3_vsn: ['3.22']
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: erlef/setup-beam@v1
         with:
           otp-version: ${{matrix.otp_vsn}}
-          rebar3-version: '3.14'
+          rebar3-version: ${{matrix.rebar3_vsn}}
+      - name: Format check
+        run: rebar3 format --verify
       - run: rebar3 test
+      - name: test our example
+        run: |
+          cd example
+          rebar3 release
+          _build/default/rel/example/bin/example daemon
+          _build/default/rel/example/bin/example ping
+      - name: Format check
+        run: |
+          cd example
+          rebar3 format --verify
+      - name: check our example
+        run: |
+          cd example
+          rebar3 test

.gitignore

@@ -1,21 +1,6 @@
-_rel/
-relx
-*.d
-.eunit
-/deps
-*.o
-*.beam
-*.plt
+_*
 erl_crash.dump
-ebin
-rel/example_project
-.concrete/DEV_MODE
 .rebar
-.erlang.mk
-log
+doc/
+.rebar3
 logs
-doc
-_build
-.rebar3/
-example/compile_commands.json
-example/_checkouts/

LICENSE

@@ -1,6 +1,6 @@
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -192,7 +192,7 @@
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
-       http://www.apache.org/licenses/LICENSE-2.0
+       https://www.apache.org/licenses/LICENSE-2.0
 
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,

README.md

@@ -1,38 +1,40 @@
-<img src="http://www.braveterry.com/wp-content/uploads/2015/03/swagger2.png"/>
+<img src="https://www.braveterry.com/wp-content/uploads/2015/03/swagger2.png"/>
 
 # cowboy-swagger
-[Swagger](http://swagger.io/) integration for [Cowboy](https://github.com/ninenines/cowboy) (built on [trails](https://github.com/inaka/cowboy-trails)).
+
+[Swagger](https://swagger.io/) integration for [Cowboy](https://github.com/ninenines/cowboy) (built on [trails](https://github.com/inaka/cowboy-trails)).
 
 ![build](https://github.com/inaka/cowboy_swagger/workflows/build/badge.svg)
 
 ## Contact Us
+
 If you find any **bugs** or have a **problem** while using this library, please
-[open an issue](https://github.com/inaka/elvis/issues/new) in this repo
+[open an issue](https://github.com/inaka/cowboy_swagger/issues/new) in this repo
 (or a pull request :)).
 
-## Requirements
-Cowboy Swagger requires Erlang 18+ after 0.1.0 version
-
 ## Why Cowboy Swagger?
+
 Simple, because there isn't a tool in Erlang to document Cowboy RESTful APIs easy and fast,
 and to improve development productivity.
 
 With `cowboy_swagger` is possible to integrate Swagger to your Erlang projects that use Cowboy as a web server.
 It is extremely easy to use, and with just a few steps you'll have a nice Web documentation for your RESTful APIs.
 
-To learn a bit more about Swagger, please check this [blog post](http://inaka.net/blog/2015/06/23/erlang-swagger-2015/).
+To learn a bit more about Swagger, please check this [blog post](https://web.archive.org/web/20161110235900/https://inaka.net/blog/2015/06/23/erlang-swagger-2015/).
 
 ## How to Use it?
+
 This is the best part. It is extremely easy.
 
 ### 1. Document each Cowboy Handler
+
 Because `cowboy_swagger` runs on top of `trails`, the first thing that you have to do
 is document all about your handler within the trails metadata. Keep in mind that
 all fields defined within each method into the metadata must be compliant with the
-[Swagger specification](http://swagger.io/specification).
+[Swagger specification](https://swagger.io/specification).
 
-For example, suppose that you have `example_echo_handler`, so it must implement the `trails/0`
-callback from `trails_handler` behaviour:
+For example, suppose that you have `example_echo_handler`, so it must implement the
+`c:trails_handler:trails/0` callback:
 
 ```erlang
 trails() ->
@@ -58,9 +60,10 @@ trails() ->
   [trails:trail("/message/[:echo]", example_echo_handler, [], Metadata)].
 ```
 
-To get a better idea of how your handler should look like, please check [here](./example/src/example_echo_handler.erl).
+To get a better idea of how your handler should look like, please check [`example/src/example_echo_handler.erl`](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example_echo_handler.erl).
 
 ### 2. Include cowboy_swagger in your app
+
 First, you need to include `cowboy_swagger_handler` module in your list of trails to be compiled.
 
 ```erlang
@@ -74,7 +77,7 @@ trails:store(Trails),
 Dispatch = trails:single_host_compile(Trails),
 ```
 
-The snippet of code above is usually placed when you start `cowboy`. Check it [here](./example/src/example.erl#L31).
+The snippet of code above is usually placed when you start `cowboy`. Check it [here](https://github.com/inaka/cowboy_swagger/blob/master/example/src/example.erl).
 
 Then add `cowboy_swagger` to the list of apps to be loaded in your `*.app.src` file.
 
@@ -140,10 +143,10 @@ Additionally, `cowboy_swagger` can be configured/customized from a `*.config` fi
 
 ### Definitions
 
-[Definitions](http://swagger.io/specification/#definitionsObject) can be used for describing
-[parameters](http://swagger.io/specification/#parametersDefinitionsObject),
-[responses](http://swagger.io/specification/#responsesDefinitionsObject) and
-[security](http://swagger.io/specification/#securityDefinitionsObject) schemas.
+[Definitions](https://swagger.io/specification/#definitionsObject) can be used for describing
+[parameters](https://swagger.io/specification/#parametersDefinitionsObject),
+[responses](https://swagger.io/specification/#responsesDefinitionsObject) and
+[security](https://swagger.io/specification/#securityDefinitionsObject) schemas.
 
 For adding definitions to your app, you have 2 choices:
 
@@ -155,6 +158,7 @@ Let's say you want to describe a `POST` call to a `newspapers` endpoint that req
 `name` and `description` fields only, you can do it like this:
 
 **Option 1:**
+
 ```erlang
 [ ... % other configurations
 , { cowboy_swagger
@@ -204,7 +208,6 @@ trails() ->
   ...
 ```
 
-
 Now in your handler's trails callback function you can use it:
 
 ```erlang
@@ -241,4 +244,5 @@ model in swagger-ui, so client developers will know exactly what parameters
 the API expects for every endpoint.
 
 ## Example
-For more information about `cowboy_swagger` and how to use it, please check this [Example](./example).
+
+For more information about `cowboy_swagger` and how to use it, please check this [Example](https://github.com/inaka/cowboy_swagger/tree/master/example).

elvis.config

@@ -1,23 +1,15 @@
-[
- {
-   elvis,
-   [
-    {config,
-     [#{dirs => ["src", "test"],
-        filter => "*.erl",
-        ruleset => erl_files,
-        rules => [{elvis_style, atom_naming_convention, #{ regex => "^(([a-z][a-z0-9]*_?)*(_SUITE)?|basePath|swagger_2_0|openapi_3_0_0)$" }}]
-       },
-      #{dirs => ["."],
-        filter => "rebar.config",
-        ruleset => rebar_config
-       },
-      #{dirs => ["."],
-        filter => "elvis.config",
-        ruleset => elvis_config
-       }
-     ]
-    }
-   ]
- }
-].
+[{elvis,
+  [{config,
+    [#{dirs => ["src", "test"],
+       filter => "*.erl",
+       ruleset => erl_files,
+       rules =>
+           [{elvis_style,
+             atom_naming_convention,
+             #{regex => "^(([a-z][a-z0-9]*_?)*(_SUITE)?|basePath|swagger_2_0|openapi_3_0_0)$"}}]},
+     #{dirs => ["."],
+       filter => "rebar.config",
+       ruleset => rebar_config},
+     #{dirs => ["."],
+       filter => "elvis.config",
+       ruleset => elvis_config}]}]}].

example/config/sys.config

@@ -1,13 +1,4 @@
-[ { example
-  , [{http_port, 8080}]
-  }
-, { cowboy_swagger
-  , [ {static_files, "priv/swagger"}
-    , { global_spec
-      , #{ openapi  => "3.0.0"
-         , info     => #{title => "Example API"}
-         }
-      }
-    ]
-  }
-].
+[{example, [{http_port, 8080}]},
+ {cowboy_swagger,
+  [{static_files, "priv/swagger"},
+   {global_spec, #{openapi => "3.0.0", info => #{title => "Example API"}}}]}].

example/config/vm.args

@@ -0,0 +1,2 @@
+-name [email protected]
+-setcookie bogus

example/rebar.config

@@ -1,41 +1,47 @@
-%% -*- mode: erlang;erlang-indent-level: 2;indent-tabs-mode: nil -*-
-%% ex: ts=4 sw=4 ft=erlang et
-
-%% == Erlang Compiler ==
-
-%% Erlang compiler options
-{erl_opts, [ warn_unused_vars
-           , warn_export_all
-           , warn_shadow_vars
-           , warn_unused_import
-           , warn_unused_function
-           , warn_bif_clash
-           , warn_unused_record
-           , warn_deprecated_function
-           , warn_obsolete_guard
-           , strict_validation
-           , warn_export_vars
-           , warn_exported_vars
-           , warn_untyped_record
-           , debug_info]}.
-
-%% == Dependencies ==
-
-{deps, [ {mixer, "1.2.0", {pkg, inaka_mixer}}
-       , cowboy_swagger
-       ]}.
+%% == Compiler and Profiles ==
+
+{erl_opts,
+ [warn_unused_import, warn_export_vars, warnings_as_errors, verbose, report, debug_info]}.
+
+{minimum_otp_vsn, "23"}.
+
+{alias, [{test, [compile, format, hank, lint, xref, dialyzer]}]}.
+
+%% == Dependencies and plugins ==
+
+{deps, [{mixer, "1.2.0", {pkg, inaka_mixer}}, cowboy_swagger]}.
+
+{project_plugins,
+ [{rebar3_hank, "~> 1.4.0"}, {rebar3_format, "~> 1.3.0"}, {rebar3_lint, "~> 3.0.1"}]}.
+
+%% == Format ==
+
+{format, [{files, ["*.config", "src/*"]}]}.
+
+%% == Hank ==
+
+{hank, [{ignore, ["_build/**", "_checkouts"]}]}.
+
+%% == Dialyzer + XRef ==
+
+{dialyzer,
+ [{warnings, [no_return, underspecs, unmatched_returns, error_handling, unknown]}]}.
+
+{xref_checks,
+ [undefined_function_calls, deprecated_function_calls, deprecated_functions]}.
+
+{xref_extra_paths, ["test/**"]}.
 
 %% == Release ==
 
-{relx, [{release, {example, "0.1"}, [example]},
-        {sys_config, "./config/sys.config"},
-        {extended_start_script, true},
-        {overlay,
-         [
-          {copy, "./_checkouts/cowboy_swagger/priv/swagger", "priv/swagger"}
-          %% The above should be changes to the following when cowboy_swagger is
+{relx,
+ [{include_src, false},
+  {extended_start_script, true},
+  {release, {example, "0.1"}, [example, sasl]},
+  {sys_config, "./config/sys.config"},
+  {vm_args, "./config/vm.args"},
+  {overlay, [{copy, "./_checkouts/cowboy_swagger/priv/swagger", "priv/swagger"}]}]}.
+
+          %% The above should be changed to the following when cowboy_swagger is
           %% used as a normal dependency (instead of _checkouts):
           %% {copy, "./_build/default/lib/cowboy_swagger/priv/swagger", "priv/swagger"}
-         ]
-        }
-       ]}.