lagom / sbt-lagom-descriptor-generator

Lagom API code generator

Deprecated - Lagom - July 1 2023

This project will only recieve security patches until July 1, 2024, at that point the project will no longer receive any additional patches.

If you are an existing customer of Lightbend and we have not yet contacted you, please reach out to Support.

We recommend migrating any existing work to:

• Akka for deeply customized projects with complex infrastructure needs. Akka now contains the vast majority of Lagom features.
• Kalix for a managed scalable environment with an abstraction above the Akka framework layer to allow you to focus only on business logic.

Lagom - The Reactive Microservices Framework

Lagom is a Swedish word meaning just right, sufficient. Microservices are about creating services that are just the right size, that is, they have just the right level of functionality and isolation to be able to adequately implement a scalable and resilient system.

Lagom focuses on ensuring that your application realizes the full potential of the Reactive Manifesto while delivering a high productivity development environment, and seamless production deployment experience.

Learn More

• Website
• Download
• Documentation
• Discuss Lagom Forum
• Get help on Stack Overflow
• Community Gitter Chat
• Contributors Gitter Chat
• Contribution Guide

License

Copyright (C) Lightbend Inc. (https://www.lightbend.com).

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://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, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

sbt-lagom-descriptor-generator's Issues

Support Swagger YAML format.

Fix build - Support Seq[T] on LagomScala descriptor code generator

Build in Travis fails because a scripted test is not passing. That test failing is a consequence of a limited support for collection types in the LagomScala code generator (see also the invalid Integration Test).

Before proceeding with other issues, it is recommended to complete the LagomScala Descriptor generation to support Seq[T] in pathParams, Request and Response types.

See also lagom/lagom#643

Detect the language of the generated code

Given other plugins configured in the service the generator should detect and generate java or scala code without user intervention.

Model types in intermediate format

Current implementation uses Service as intermediate model but it only models the Service Descriptor and ignores the types (uses String) to represent types.

We should have a modelling system that enables Swagger-to-Lagom and Lagom-to-Lagom representation.

Replace mockup render with templating engine

Current implementation uses a String concat approach to rendering the generated code.

xxxLagomGenerators could use mustache, velocity, twirl for the generation.

Parameterize output package name

Current sbt plugin will output code into a package equal to the organization name of the sbt project. This value should be overridable by the end user.

See

sbt-lagom-descriptor-generator/lagom-descriptor-generator-sbt-plugin/src/main/scala/com/lightbend/lagom/spec/sbt/LagomOpenApiGenerator.scala

Line 36 in 070a71d

val packageName = organization.value

Detect and process many spec files

A service consuming many downstream services will have many swagger-xxx.json files on src/main/openapi. All should be processed separately.

Support additional properties of incoming messages

Applying Postel's Law parsing a message should be liberal. JsonSchema supports setting up the additonalProperties flag to control that. Enumerated fields may also increase the set of valid values ("male"/"female" v "male"/"female"/"won't disclose").

There are three possible scenarios:

1. strict parsing fails when new fields arrive
2. liberal parsing doesn't fail
3. liberal parsing doesn't fail and includes the additionalFields as an extra data in the parsed objects (final Map<String,Object> additionalFields)

As a general rule, the generated code should be robust to exta fields arriving on a message (options 2 and 3). This issue is to implement code generators that are liberal and also to discuss whether extra info should be made available to users (3) or simply swallowed (2).

• the generated code should allow for liberal parsing (must do)
• generating code from swagger should honour the value of additionalProperties (may do)
• add an UNKNOWN field on enums so that parsing new values in the set doesn't cause issues. This is not explicitly supported in jsonSchema. (may do)

Parameterize Api naming

Current sbt plugin will use the source file name as the base for the output service api class name (interface or trait). This leads to non-idiomatic names and is very unflexible. End users should be able to provide a Map[String, String] on sbt settings:

Map( `petservice.json` -> `MyPetService`)

See

sbt-lagom-descriptor-generator/lagom-descriptor-generator-sbt-plugin/src/main/scala/com/lightbend/lagom/spec/sbt/LagomOpenApiGenerator.scala

Line 42 in 070a71d

val serviceName = extractServiceName(specFile.getName)

Support multiple Lagom versions

It'd be good, as Lagom evolves to be able to generate the code of different Lagom version if/when APIs in Lagom break or include new features.

E.g. the current status of the code generator was tested with Lagom 1.4.0-SNAPSHOT. The Java code generator would work with Lagom 1.1.0+ but not the scala code generator (the Lagom scala API was introduced in Lagom 1.3.x). Same goes if generating code for an old version that didn't support message publishing.

Use scalariform on generated code

Even if formatted code will rarely be read by humans, it'd be good if it's reasonably well formatted.

We have two alternatives to achieve it:
a) being disciplined and count blankspaces in the templates
b) using scalariform or similar to do the heavy lifting.

Generate PathParamSerializers for enum in javadsl

Generated Descriptors for javadsl overlooked path param serializers.

The scripted test for petstore-java for example compiles but won't run because at least the following path param serializers for the StatusEnum query param in findPetsByStatus is missing.

.withPathParamSerializer(
                StatusEnum.class, 
                PathParamSerializers.required(
                        "Status",
                        StatusEnum::fromValue,
                        StatusEnum::toString)
        );

Create naming tools to standardize service, class and method names

External Spec formats allow inline Definition of types or consider some fields optional which are required for Lagom.

Naming tools should normalize for the purpose (service name, class name, method name, call name) or even generate unique names when the input doesn't specify the Lagom required field (specifying the request body type in swagger inline doesn't require a name).

Enable data filtering

LagomGenerator allows filtering. A user should be able to plug a Service => Service to customize the generator.

Render Spec-defined types

Swagger (and other specs) define types for request/response/params.

Once #7 is ongoing, a rendering of this spec-defined types is required.

This issue only represents the actual code generation: from the intermediate format to the actual generated code.

It is responsibility of each spec parser to grant the correct conversion from the spec format to our intermediate format.

mvn plugin

A user including this plugin should get code generated for each xyz-swagger.json file in src/main/openapi-v2.
Then the user would have to either bindClient or implement and bindService each Service generated.

Target language (scala/java) should be picked up from the available implementation)

See #10

sbt plugin

A user including this plugin should get code generated for each xyz-swagger.json file in src/main/openapi-v2.
Then the user would have to either bindClient or implement and bindService each Service generated.

Target language (scala/java) should be picked up from the available implementation).

See #11

Rename repo

If this repository contains Maven and sbt support it will need to be renamed.

Setup scalariform

Add CONTRIBUTING.md

Setup sbt-license to include license headers on sources