Updated README.mustache template for the Erlang server generator (#20138

) * Updated README.mustache file for the Erlang server generator. Fixed one error and updated the usage instructions Changes made to the Erlang server generator's user instructions ("README.mustache" file): 1. Corrected the argument in section 4.1 of the user instructions. In openapi_server:start/2, the second argument for the generated Erlang code must now be in a different format than proposed in the instructions (see lines 13-16 of the "server.mustache" file). Initially, the server failed to start, and after some debugging, I discovered that the argument format did not match the server's expectations, causing the port number not to be passed to cowboy:start_clear/3. This has now been fixed. 2. Reviewed and updated the text of the user instructions to remove any ambiguities. 3. Tested the user instructions for accuracy and completeness. * erlang-server sample recompiled * README fix * Fixed README.mustache template markdown for erlang-server. Re-generated erlang-server sample. * Update README.mustache * Sample 'erlang-server' re-generated * update samples --------- Co-authored-by: William Cheng <[email protected]>
OpenAPITools · Nov 30, 2024 · 3f6c3de · 3f6c3de
1 parent 878148e
commit 3f6c3de
Show file tree

Hide file tree

Showing 3 changed files with 330 additions and 60 deletions.
diff --git a/modules/openapi-generator/src/main/resources/erlang-server/README.mustache b/modules/openapi-generator/src/main/resources/erlang-server/README.mustache
@@ -4,33 +4,123 @@
 
 An Erlang server stub generated by [OpenAPI Generator](https://openapi-generator.tech) given an OpenAPI spec.
 
-Dependencies: Erlang OTP/27 and rebar3. Also:
-- [Cowboy](https://hex.pm/packages/cowboy)
-- [Ranch](https://hex.pm/packages/ranch)
-- [Jesse](https://hex.pm/packages/jesse)
-
 ## Prerequisites
 
+1. [Erlang/OTP (v27)](https://www.erlang.org/)
+
+2. [rebar3](https://rebar3.org/)
+
+3. Erlang libraries:
+    - [Cowboy](https://hex.pm/packages/cowboy)
+    - [Ranch](https://hex.pm/packages/ranch)
+    - [Jesse](https://hex.pm/packages/jesse)
+
+4. OpenAPI generator script `openapi-generator-cli` 
+(for more information see [OpenAPI Generator - Getting Started](https://github.com/OpenAPITools/openapi-generator#2---getting-started) )
+
+5. OpenAPI specification file in the current folder (for example [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml))
+
+
 ## Getting started
-Use erlang-server with rebar3
+Use `erlang-server` with `rebar3`
+
+1. Create a folder with an Erlang application by using `rebar3`
+
+    `$ rebar3 new app http_server`
+
+2. Generate OpenAPI `erlang-server` project using `openapi-generator`
+
+    `$ openapi-generator-cli generate -g erlang-server -i petstore.yaml -o ./http_server --additional-properties packageName=openapi`
+
+3. Go into the `http_server` project folder
+
+    `$ cd http_server`
+
+    NOTE: The following generated files are now in the folder "http_server":
+
+    - `src/http_server*.erl`, `http_server.app.src` -- Erlang application modules generated by `rebar3`
+
+    - `src/openapi*.erl`, `openapi.app.src` -- REST API request handling modules generated by `openapi-generator-cli`
+
+    - `priv/openapi.json` -- OpenAPI data in JSON format created by `openapi-generator-cli`
 
-	1, Create an application by using rebar3
-		$ rebar3 new app http_server
+    - `rebar.config` -- Erlang project configuration file generated by `openapi-generator-cli`
 
-	2, Generate erlang-server project using openapi-generator
-		https://github.com/OpenAPITools/openapi-generator#2---getting-started
+4. Add the following line to the `start/2` function in the `src/http_server_app.erl`:
 
-	3, Copy erlang-server file to http_server project, and don't forget the 'priv' folder.
+```erlang
+    openapi_server:start(http_server,
+        #{transport_opts => [{ip,{127,0,0,1}},
+                             {port,8080} 
+                            ]})
+```
 
-	4, Start in the http_server project:
-		1, Introduce the following line in the http_server_app:start(_Type, _Args) function
-			openapi_server:start(http_server, #{ip => {127,0,0,1}, port => 8080})
-		2, Compile your http_server project
-			$ rebar3 compile
-		3, Start erlang virtual machine
-			$ rebar3 shell
-		4, Start project
-			application:ensure_all_started(http_server).
+The updated `start/2` in `src/http_server_app.erl` should look like this:
+
+```erlang
+start(_StartType, _StartArgs) ->
+    openapi_server:start(http_server,
+        #{transport_opts => [{ip,{127,0,0,1}},
+                             {port,8080} 
+                            ]}),
+    http_server_sup:start_link().
+```
+
+5. Update application configuration file `http_server.app.src` (in the `src` subfolder):
+
+    1. Copy application name from `http_server.app.src` to `openapi.app.src`
+
+    2. Copy `{mod,...}` rule from the `http_server.app.src` to `openapi.app.src`
+
+    3. Copy `openapi.app.src` over `http_server.app.src`
+
+        `$ cp src/openapi.app.src src/http_server.app.src`
+
+    4. Remove `openapi.app.src`
+
+        `$ rm src/openapi.app.src`
+
+The updated `src/http_server.app.src` must be the only configuration file in the project and it should look like this:
+
+```
+{application, http_server,
+    [   {description, "This is a sample petstore server"},
+        {vsn, "1.0.0"},
+        {registered, []},
+        {mod, {http_server_app, []}},
+        {applications, [kernel, stdlib, public_key, ssl, inets, ranch, cowboy]},
+        {env, []},
+        {modules, []},
+        {licenses, ["Apache-2.0"]},
+        {links, []}
+    ]}.
+```
+
+6. Compile your `http_server` project
+
+    `$ rebar3 compile`
+
+7. Start Erlang virtual machine
+    `$ rebar3 shell`
+
+8. Start the application by running a following command in the `rebar3` shell
+
+    `1> application:ensure_all_started(http_server).`
+
+    Alternatively, you could start your application with the `rebar3` shell by adding the following lines to the `rebar.config`:
+    ```
+    {shell, [
+        {apps, [http_server]}
+    ]}.
+    ```
+
+Note: If you need to repeat code generation using `openapi-generator-cli`, but don't want to rewrite changes in files made manually, you could use file `.openapi-generator-ignore` in the project root folder. For example, such `.openapi-generator-ignore` will preserve manual changes done in the file `rebar.conf` (Point 8)
+
+```
+# OpenAPI Generator Ignore
+rebar.config
+```
 
 To implement your own business logic, create a module called `http_server_logic` that implements the
 behaviour `openapi_logic_handler`. Refer to `openapi_logic_handler` documentation for details.
+
diff --git a/samples/server/echo_api/erlang-server/README.md b/samples/server/echo_api/erlang-server/README.md
@@ -4,33 +4,123 @@
 
 An Erlang server stub generated by [OpenAPI Generator](https://openapi-generator.tech) given an OpenAPI spec.
 
-Dependencies: Erlang OTP/27 and rebar3. Also:
-- [Cowboy](https://hex.pm/packages/cowboy)
-- [Ranch](https://hex.pm/packages/ranch)
-- [Jesse](https://hex.pm/packages/jesse)
-
 ## Prerequisites
 
+1. [Erlang/OTP (v27)](https://www.erlang.org/)
+
+2. [rebar3](https://rebar3.org/)
+
+3. Erlang libraries:
+    - [Cowboy](https://hex.pm/packages/cowboy)
+    - [Ranch](https://hex.pm/packages/ranch)
+    - [Jesse](https://hex.pm/packages/jesse)
+
+4. OpenAPI generator script `openapi-generator-cli` 
+(for more information see [OpenAPI Generator - Getting Started](https://github.com/OpenAPITools/openapi-generator#2---getting-started) )
+
+5. OpenAPI specification file in the current folder (for example [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml))
+
+
 ## Getting started
-Use erlang-server with rebar3
+Use `erlang-server` with `rebar3`
+
+1. Create a folder with an Erlang application by using `rebar3`
+
+    `$ rebar3 new app http_server`
+
+2. Generate OpenAPI `erlang-server` project using `openapi-generator`
+
+    `$ openapi-generator-cli generate -g erlang-server -i petstore.yaml -o ./http_server --additional-properties packageName=openapi`
+
+3. Go into the `http_server` project folder
+
+    `$ cd http_server`
+
+    NOTE: The following generated files are now in the folder "http_server":
+
+    - `src/http_server*.erl`, `http_server.app.src` -- Erlang application modules generated by `rebar3`
+
+    - `src/openapi*.erl`, `openapi.app.src` -- REST API request handling modules generated by `openapi-generator-cli`
+
+    - `priv/openapi.json` -- OpenAPI data in JSON format created by `openapi-generator-cli`
 
-	1, Create an application by using rebar3
-		$ rebar3 new app http_server
+    - `rebar.config` -- Erlang project configuration file generated by `openapi-generator-cli`
 
-	2, Generate erlang-server project using openapi-generator
-		https://github.com/OpenAPITools/openapi-generator#2---getting-started
+4. Add the following line to the `start/2` function in the `src/http_server_app.erl`:
 
-	3, Copy erlang-server file to http_server project, and don't forget the 'priv' folder.
+```erlang
+    openapi_server:start(http_server,
+        #{transport_opts => [{ip,{127,0,0,1}},
+                             {port,8080} 
+                            ]})
+```
 
-	4, Start in the http_server project:
-		1, Introduce the following line in the http_server_app:start(_Type, _Args) function
-			openapi_server:start(http_server, #{ip => {127,0,0,1}, port => 8080})
-		2, Compile your http_server project
-			$ rebar3 compile
-		3, Start erlang virtual machine
-			$ rebar3 shell
-		4, Start project
-			application:ensure_all_started(http_server).
+The updated `start/2` in `src/http_server_app.erl` should look like this:
+
+```erlang
+start(_StartType, _StartArgs) ->
+    openapi_server:start(http_server,
+        #{transport_opts => [{ip,{127,0,0,1}},
+                             {port,8080} 
+                            ]}),
+    http_server_sup:start_link().
+```
+
+5. Update application configuration file `http_server.app.src` (in the `src` subfolder):
+
+    1. Copy application name from `http_server.app.src` to `openapi.app.src`
+
+    2. Copy `{mod,...}` rule from the `http_server.app.src` to `openapi.app.src`
+
+    3. Copy `openapi.app.src` over `http_server.app.src`
+
+        `$ cp src/openapi.app.src src/http_server.app.src`
+
+    4. Remove `openapi.app.src`
+
+        `$ rm src/openapi.app.src`
+
+The updated `src/http_server.app.src` must be the only configuration file in the project and it should look like this:
+
+```
+{application, http_server,
+    [   {description, "This is a sample petstore server"},
+        {vsn, "1.0.0"},
+        {registered, []},
+        {mod, {http_server_app, []}},
+        {applications, [kernel, stdlib, public_key, ssl, inets, ranch, cowboy]},
+        {env, []},
+        {modules, []},
+        {licenses, ["Apache-2.0"]},
+        {links, []}
+    ]}.
+```
+
+6. Compile your `http_server` project
+
+    `$ rebar3 compile`
+
+7. Start Erlang virtual machine
+    `$ rebar3 shell`
+
+8. Start the application by running a following command in the `rebar3` shell
+
+    `1> application:ensure_all_started(http_server).`
+
+    Alternatively, you could start your application with the `rebar3` shell by adding the following lines to the `rebar.config`:
+    ```
+    {shell, [
+        {apps, [http_server]}
+    ]}.
+    ```
+
+Note: If you need to repeat code generation using `openapi-generator-cli`, but don't want to rewrite changes in files made manually, you could use file `.openapi-generator-ignore` in the project root folder. For example, such `.openapi-generator-ignore` will preserve manual changes done in the file `rebar.conf` (Point 8)
+
+```
+# OpenAPI Generator Ignore
+rebar.config
+```
 
 To implement your own business logic, create a module called `http_server_logic` that implements the
 behaviour `openapi_logic_handler`. Refer to `openapi_logic_handler` documentation for details.
+