New generator - Scala Play Framework #2421

adigerber · 2019-03-15T20:47:39Z

PR checklist

Read the contribution guidelines.
Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh, ./bin/security/{LANG}-petstore.sh and ./bin/openapi3/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
Filed the PR against the correct branch: master~~, 3.4.x, 4.0.x~~. Default: master.
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

This is work in progress!

This PR introduces a new generator definition - Scala Play Framework.

Features

CC (technical committee): @clasnake, @jimschubert, @shijinkui, @ramzimaalej

Migrated from swagger-codegen

Note this was originally written for swagger-codegen so there may be some remnants around in the code before this is fully complete.

Some issues that need attention:

Default values for stubs - check if given schema/property is required
When generating against modules/openapi-generator/src/test/resources/3_0/petstore.yaml, models InlineObject and InlineObject1 are generated but are not used anywhere at the moment Edit: removed these files by running the generator with -DskipFormModel=true
Enums are generated inside their parent object (e.g. Pet.Status), but there is no context of the parent object in the API operations so enumName and datatypeWithEnum do not reference the enum (e.g. Status instead of Pet.Status). Couldn't find a way to inject the parent model name anywhere. Edit: since java-play-framework does not convert enum params in operations this will not be done here either.
Friendly output of JsResultException (New generator - Scala Play Framework #2421 (comment))

…-> dataType

jimschubert

Thanks for working on this new generator! I've left a few comments. I'll check back when the PR is no longer draft or if you are looking for additional feedback during implementation.

jimschubert · 2019-03-17T15:03:58Z

...es/openapi-generator/src/main/resources/scala-play-framework/simpleParentJsonFormat.mustache

@@ -0,0 +1,7 @@
+{{! Keep indentation at 4 spaces for proper formatting of the output. }}


I've found mustache to be inconsistent with indents in some situations. I don't remember the specifics, but I think indents may be dropped in files at an import depth greater than 1?

To resolve the issue I had created a lambda that you can reuse if the indents become an issue. See the kotlin-server generator. Example usage of the lambda: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/kotlin-server/libraries/ktor/_api_body.mustache

Thanks! I'll try experimenting more with the indents and if nothing works I'll give this method a shot.

jimschubert · 2019-03-17T15:19:08Z

...erator/src/main/java/org/openapitools/codegen/languages/ScalaPlayFrameworkServerCodegen.java

+
+public class ScalaPlayFrameworkServerCodegen extends AbstractScalaCodegen implements CodegenConfig {
+    public static final String TITLE = "title";
+    public static final String IMPL_STUBS = "implStubs";


I think this name may be confusing, as it indicates generation of stubbed implementations... but this is a default behavior in most generators that support interfaces.

I'm wondering if this is the same option in the Java Play generator, controllerOnly:

Whether to generate only API interface stubs without the server files.

If so, we may want to align the option name to avoid confusion for those evaluating the Play generation with different languages. This wouldn't be necessary in this PR, though. I just wanted to document the thought.

implStubs is similar to controllerOnly in that they both affect whether stubs are generated, but controllerOnly also affects the interface in java-play-framework, while in this generator I wish to allow generating the trait regardless of the stubs. Perhaps I should make both configurable?

Also in the spirit of keeping things similar, I'll rename apiFutures to supportAsync.

jimschubert · 2019-03-17T15:21:12Z

modules/openapi-generator/src/main/resources/scala-play-framework/LICENSE.mustache

@@ -0,0 +1,8 @@
+This software is licensed under the Apache 2 license, quoted below.


We probably don't want to enforce a LICENSE in the template.

jimschubert · 2019-03-17T15:25:11Z

modules/openapi-generator/src/main/resources/scala-play-framework/caseClass.mustache

+    val {{.}} = Value{{/values}}{{/allowableValues}}
+
+    type {{enumName}} = Value
+    implicit lazy val {{enumName}}JsonFormat: Format[Value] = Format(Reads.enumNameReads(this), Writes.enumNameWrites[this.type])


May want to import Format and other Json related types at the object level here and/or above line 7, otherwise this assumes they exist in the including mustache file.

This is a partial that's only used in model.mustache which has this import. I split the model into three main partials (arrayCaseClass.mustache, caseClass.mustache and caseObject.mustache) in an attempt to keep it somewhat cleaner.

…ead of opt-in)

…alse

…better default responses

wing328 · 2019-03-25T13:43:40Z

From the list, looks like many items have been completed. Great work @adigerber !

What about adding the auto-generated README and then we'll release a beta version to collect feedback from the community?

adigerber · 2019-03-25T14:26:21Z

@wing328 Sure, will do later today.

adigerber · 2019-03-25T22:01:35Z

@wing328 I added the README, but I think there's more work to be done before even beta release, specifically - error handling (i.e. converting exceptions to suitable HTTP responses).
I've already started working on that a few days ago but haven't had the time to finish. I'll see if I can get it done within the next couple hours.

- Fix Indentation using mustache lambdas - Option to set routes file name (default: routes) - allows uninterrupted manual maintenance of main routes file, which may include a subroute to the generated routes file - Move supporting file classes to a package and update application.conf generation accordingly - Option to generate custom exceptions (default: true) which are used in the controller to differentiate between API call exceptions and validation exceptions - Generate error handler with basic exception mapping - Option to generate API docs under /api route - Reorder routes file so parameter-less paths are given priority over parameterized paths. Prevents case like /v2/user/:username activating before /v2/user/login (thus shadowing the login route completely) as observed using v3 petstore.yaml - Option to set base package name (default: org.openapitools) to allow placing supporting files under a different package

adigerber · 2019-03-26T01:13:30Z

I've finished most of the code generation I wanted to do.
I generated a clean sample (using bin/scala-play-framework-petstore.sh), which builds successfully and runs seemingly without problems (tested JSON body, query string and form parameters including file uploads).

One small fix I have planned is to correctly format JsResultException - when sending a request to an endpoint which expects a JSON object with required properties, if the requirements aren't met a JsResultException is thrown by Play's JSON library. This is caught in the generated error handler, which in turn responds with HTTP 400, but the output is not friendly:

JsResultException(errors:List((/photoUrls,List(JsonValidationError(List(error.path.missing),WrappedArray()))), (/name,List(JsonValidationError(List(error.path.missing),WrappedArray())))))

Apart from tests and the above fix this generator should be ready :-]

wing328 · 2019-03-26T01:29:34Z

@adigerber thanks. I'll take a look and merge it into master later today if no question from me.

adigerber · 2019-03-26T06:59:01Z

@wing328 Sure. Something is preventing Circle CI from approving the PR though, so I'll see what I can do about it.

CC (technical committee; for final review): @clasnake, @jimschubert, @shijinkui, @ramzimaalej

wing328 · 2019-03-26T08:03:14Z

Tested locally and the result looks good.

wing328 · 2019-03-26T08:04:44Z

I'll update the doc and make some other minor enhancements in a separate PR

wing328 · 2019-03-27T05:39:16Z

#2512 merged into master with some minor enhancements made to the Scala play generator.

wing328 · 2019-03-27T08:39:31Z

Tweet to promote the new generator: https://twitter.com/oas_generator/status/1110821644774178816

Reddit: https://www.reddit.com/r/scala/comments/b5zb53/generate_scala_play_server_stub_using_openapi/

Show HN: https://news.ycombinator.com/item?id=19497940

adigerber added 3 commits March 15, 2019 22:40

Added new generator for Scala + Play Framework (WIP)

36ec36a

scala-play-framework: default values reintroduced (mostly); datatype …

f44107f

…-> dataType

reintroduced missing EOF newline

953dc52

jimschubert reviewed Mar 17, 2019

View reviewed changes

adigerber added 5 commits March 18, 2019 01:26

Support single/collection params for header/query params

2e963ea

Rename apiFutures > supportAsync, implStubs > skipStubs (opt-out inst…

1ded05b

…ead of opt-in)

Deleted license and small fixes

36999c6

Generate extraction of form parameters from request body

b0543ba

Added missing call to executeApi for unit methods when supportAsync=f…

43bfd0d

…alse

wing328 added Enhancement: New generator Server: Scala labels Mar 19, 2019

adigerber added 2 commits March 21, 2019 01:23

Polished some stuff and added routes, application.conf, logback.xml, …

a02939d

…better default responses

Disabled generation of Json.format for models with files

8dbc2be

wing328 added this to the 4.0.0 milestone Mar 25, 2019

Added README

28d06a0

adigerber added 5 commits March 26, 2019 02:02

Revert supportAsync default to false

2deb2f2

Added binaries and default api/model packages

b729a93

Added scala-play-framework sample

0c9e923

Add missing contextPath to README and controller comment

04dd093

wing328 marked this pull request as ready for review March 26, 2019 01:28

wing328 merged commit 28ae33c into OpenAPITools:master Mar 26, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New generator - Scala Play Framework #2421

New generator - Scala Play Framework #2421

adigerber commented Mar 15, 2019 •

edited

Loading

jimschubert left a comment

jimschubert Mar 17, 2019

adigerber Mar 17, 2019

jimschubert Mar 17, 2019

adigerber Mar 17, 2019

jimschubert Mar 17, 2019

jimschubert Mar 17, 2019

adigerber Mar 17, 2019

wing328 commented Mar 25, 2019

adigerber commented Mar 25, 2019

adigerber commented Mar 25, 2019

adigerber commented Mar 26, 2019

wing328 commented Mar 26, 2019

adigerber commented Mar 26, 2019

wing328 commented Mar 26, 2019

wing328 commented Mar 26, 2019

wing328 commented Mar 27, 2019

wing328 commented Mar 27, 2019

		@@ -0,0 +1,7 @@
		{{! Keep indentation at 4 spaces for proper formatting of the output. }}

		@@ -0,0 +1,8 @@
		This software is licensed under the Apache 2 license, quoted below.

New generator - Scala Play Framework #2421

New generator - Scala Play Framework #2421

Conversation

adigerber commented Mar 15, 2019 • edited Loading

PR checklist

Description of the PR

Features

Migrated from swagger-codegen

jimschubert left a comment

Choose a reason for hiding this comment

jimschubert Mar 17, 2019

Choose a reason for hiding this comment

adigerber Mar 17, 2019

Choose a reason for hiding this comment

jimschubert Mar 17, 2019

Choose a reason for hiding this comment

adigerber Mar 17, 2019

Choose a reason for hiding this comment

jimschubert Mar 17, 2019

Choose a reason for hiding this comment

jimschubert Mar 17, 2019

Choose a reason for hiding this comment

adigerber Mar 17, 2019

Choose a reason for hiding this comment

wing328 commented Mar 25, 2019

adigerber commented Mar 25, 2019

adigerber commented Mar 25, 2019

adigerber commented Mar 26, 2019

wing328 commented Mar 26, 2019

adigerber commented Mar 26, 2019

wing328 commented Mar 26, 2019

wing328 commented Mar 26, 2019

wing328 commented Mar 27, 2019

wing328 commented Mar 27, 2019

adigerber commented Mar 15, 2019 •

edited

Loading