Merge pull request #1 from novaframework/add-developer-tools

Add developer tools section

Author: Taure

examples/my_first_nova/priv/schemas/product.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "id": { "type": "integer", "description": "Unique identifier" },
+    "name": { "type": "string", "description": "Product name" },
+    "price": { "type": "number", "description": "Price in cents" },
+    "description": { "type": "string", "description": "Product description" }
+  },
+  "required": ["name", "price"]
+}

examples/my_first_nova/priv/schemas/user.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "id": { "type": "integer", "description": "Unique identifier" },
+    "name": { "type": "string", "description": "User's full name" },
+    "email": { "type": "string", "format": "email", "description": "Email address" }
+  },
+  "required": ["name", "email"]
+}

examples/my_first_nova/src/controllers/my_first_nova_products_controller.erl

@@ -0,0 +1,41 @@
+-module(my_first_nova_products_controller).
+-export([
+         list/1,
+         show/1,
+         create/1,
+         update/1,
+         delete/1
+        ]).
+
+list(_Req) ->
+    Products = [
+        #{id => 1, name => <<"Widget">>, price => 999, description => <<"A fine widget">>},
+        #{id => 2, name => <<"Gadget">>, price => 1999, description => <<"A fancy gadget">>}
+    ],
+    {json, #{products => Products}}.
+
+show(#{bindings := #{<<"id">> := Id}}) ->
+    {json, #{id => binary_to_integer(Id),
+             name => <<"Widget">>,
+             price => 999,
+             description => <<"A fine widget">>}};
+show(_Req) ->
+    {status, 400, #{}, #{error => <<"missing id">>}}.
+
+create(#{params := #{<<"name">> := Name, <<"price">> := Price}} = Req) ->
+    Desc = maps:get(<<"description">>, maps:get(params, Req, #{}), <<>>),
+    {json, 201, #{}, #{id => 3, name => Name, price => Price, description => Desc}};
+create(_Req) ->
+    {status, 422, #{}, #{error => <<"name and price required">>}}.
+
+update(#{bindings := #{<<"id">> := Id},
+         params := #{<<"name">> := Name, <<"price">> := Price}} = Req) ->
+    Desc = maps:get(<<"description">>, maps:get(params, Req, #{}), <<>>),
+    {json, #{id => binary_to_integer(Id), name => Name, price => Price, description => Desc}};
+update(_Req) ->
+    {status, 422, #{}, #{error => <<"name and price required">>}}.
+
+delete(#{bindings := #{<<"id">> := _Id}}) ->
+    {status, 204};
+delete(_Req) ->
+    {status, 400, #{}, #{error => <<"missing id">>}}.

examples/my_first_nova/src/my_first_nova_router.erl

@@ -66,7 +66,12 @@ routes(_Environment) ->
                  {"/notes/:id", fun my_first_nova_notes_api_controller:delete/1, #{methods => [delete]}},
                  {"/users", fun my_first_nova_api_controller:index/1, #{methods => [get]}},
                  {"/users/:id", fun my_first_nova_api_controller:show/1, #{methods => [get]}},
-                 {"/users", fun my_first_nova_api_controller:create/1, #{methods => [post]}}
+                 {"/users", fun my_first_nova_api_controller:create/1, #{methods => [post]}},
+                 {"/products", fun my_first_nova_products_controller:list/1, #{methods => [get]}},
+                 {"/products/:id", fun my_first_nova_products_controller:show/1, #{methods => [get]}},
+                 {"/products", fun my_first_nova_products_controller:create/1, #{methods => [post]}},
+                 {"/products/:id", fun my_first_nova_products_controller:update/1, #{methods => [put]}},
+                 {"/products/:id", fun my_first_nova_products_controller:delete/1, #{methods => [delete]}}
                 ]
     }
   ].

examples/my_first_nova/test/my_first_nova_products_controller_tests.erl

@@ -0,0 +1,33 @@
+-module(my_first_nova_products_controller_tests).
+-include_lib("eunit/include/eunit.hrl").
+
+list_returns_products_test() ->
+    Req = #{},
+    Result = my_first_nova_products_controller:list(Req),
+    ?assertMatch({json, #{products := [_|_]}}, Result).
+
+show_existing_product_test() ->
+    Req = #{bindings => #{<<"id">> => <<"1">>}},
+    Result = my_first_nova_products_controller:show(Req),
+    ?assertMatch({json, #{id := 1, name := _, price := _}}, Result).
+
+create_with_valid_params_test() ->
+    Req = #{params => #{<<"name">> => <<"Widget">>, <<"price">> => 999}},
+    Result = my_first_nova_products_controller:create(Req),
+    ?assertMatch({json, 201, #{}, #{id := 3, name := <<"Widget">>, price := 999}}, Result).
+
+create_missing_params_test() ->
+    Req = #{},
+    Result = my_first_nova_products_controller:create(Req),
+    ?assertMatch({status, 422, _, _}, Result).
+
+update_product_test() ->
+    Req = #{bindings => #{<<"id">> => <<"1">>},
+            params => #{<<"name">> => <<"Updated">>, <<"price">> => 1500}},
+    Result = my_first_nova_products_controller:update(Req),
+    ?assertMatch({json, #{id := 1, name := <<"Updated">>, price := 1500}}, Result).
+
+delete_product_test() ->
+    Req = #{bindings => #{<<"id">> => <<"1">>}},
+    Result = my_first_nova_products_controller:delete(Req),
+    ?assertMatch({status, 204}, Result).

src/SUMMARY.md

@@ -30,6 +30,12 @@
 - [Sub-Applications](building-app/sub-applications.md)
 - [Deployment](building-app/deployment.md)
 
+# Developer Tools
+
+- [Code Generators](developer-tools/code-generators.md)
+- [OpenAPI & API Documentation](developer-tools/openapi.md)
+- [Inspection & Audit Tools](developer-tools/inspection-tools.md)
+
 # Going Further
 
 - [Pub/Sub](going-further/pubsub.md)

src/appendix/cheat-sheet.md

@@ -199,3 +199,29 @@ nova_pubsub:get_local_members(Channel)
 | `rebar3 as prod release` | Build production release |
 | `rebar3 as prod tar` | Build release tarball |
 | `rebar3 dialyzer` | Run type checker |
+
+## Nova developer tool commands
+
+| Command | Description |
+|---|---|
+| `rebar3 nova gen_controller --name NAME` | Generate a controller with stub actions |
+| `rebar3 nova gen_resource --name NAME` | Generate controller + JSON schema + route hints |
+| `rebar3 nova gen_test --name NAME` | Generate a Common Test suite |
+| `rebar3 nova openapi` | Generate OpenAPI 3.0.3 spec + Swagger UI |
+| `rebar3 nova config` | Show Nova configuration with defaults |
+| `rebar3 nova middleware` | Show global and per-group plugin chains |
+| `rebar3 nova audit` | Find routes missing security callbacks |
+| `rebar3 nova release` | Build release with auto-generated OpenAPI |
+
+### Generator options
+
+```shell
+# Controller with specific actions
+rebar3 nova gen_controller --name products --actions list,show,create
+
+# OpenAPI with custom output
+rebar3 nova openapi --output priv/assets/openapi.json --title "My API" --api-version 1.0.0
+
+# Release with specific profile
+rebar3 nova release --profile staging
+```

src/building-apis/json-apis.md

@@ -6,7 +6,15 @@ So far we have been rendering HTML views with ErlyDTL templates. Now let's build
 
 Instead of returning `{ok, Variables}` (which renders a template), return `{json, Data}` and Nova encodes it as JSON with the correct `Content-Type` header.
 
-Create `src/controllers/my_first_nova_api_controller.erl`:
+You can scaffold an API controller quickly with the code generator:
+
+```shell
+rebar3 nova gen_resource --name users --actions index,show,create
+```
+
+This generates a controller with stub functions, a JSON schema, and prints route definitions. See [Code Generators](../developer-tools/code-generators.md) for the full details.
+
+Let's write the controller by hand so we can see what each part does. Create `src/controllers/my_first_nova_api_controller.erl`:
 
 ```erlang
 -module(my_first_nova_api_controller).

src/building-app/crud-app.md

@@ -96,7 +96,17 @@ row_to_map({Id, Title, Body, Author, InsertedAt}) ->
 
 ## JSON API controller
 
-Create `src/controllers/my_first_nova_notes_api_controller.erl`:
+We can scaffold the API controller and a JSON schema in one step with the code generator:
+
+```shell
+rebar3 nova gen_resource --name notes
+===> Writing src/controllers/my_first_nova_notes_api_controller.erl
+===> Writing priv/schemas/note.json
+```
+
+This gives us a controller with stub functions and a JSON schema that the [OpenAPI generator](../developer-tools/openapi.md) can pick up later. Now let's replace the stubs with our actual implementation.
+
+Create (or replace) `src/controllers/my_first_nova_notes_api_controller.erl`:
 
 ```erlang
 -module(my_first_nova_notes_api_controller).

src/building-app/deployment.md

@@ -115,6 +115,17 @@ Build a production release:
 rebar3 as prod release
 ```
 
+If you have JSON schemas in `priv/schemas/`, you can use `nova release` instead. It automatically regenerates the OpenAPI spec before building:
+
+```shell
+rebar3 nova release
+===> Generated priv/assets/openapi.json
+===> Generated priv/assets/swagger.html
+===> Release successfully assembled: _build/prod/rel/my_first_nova
+```
+
+This ensures your deployed application always ships with up-to-date API documentation. See [OpenAPI & API Documentation](../developer-tools/openapi.md) for details.
+
 Start it:
 
 ```shell