CONTRIBUTING.md

Project structure

• root: Contains tests and nothing else
  • cli: CLI driver and argument parser
  • core: Tagless Final traits, SPI loaders, and core data structures
  • java-async-http: Generators for async-http-client
  • java-dropwizard: Generators for dropwizard
  • java-spring-mvc: Generators for spring-mvc
  • java-support: Language definitions for Java, as well as Jackson generators
  • scala-akka-http: Generators for akka-http clients and servers
  • scala-dropwizard: Generators for dropwizard
  • scala-http4s: Generators for http4s clients and servers
  • scala-support: Language definitions for Scala, as well as circe and Jackson generators

Coding guidelines

• Readability
• Maintainability
• Testability
• Defer effects
• Typesafe accessors for Java function calls
  • Extractable
  • VendorExtensible
  • Tracker

Writing integration Tests

It is difficult to tell if the code generated by the tool is functional and type sound by structure alone. As unit tests are not enough, integration tests actually run guardrail as a CLI tool to generate complete clients and servers, ensuring everything works as expected.

The projects defined at modules/sample-* contain:

• target/generated: Sources generated by runScalaExample or runJavaExample
• src/main: Support definitions for generated code
• src/test: Manually written integration tests against the generated code. These tests are run by the runtimeScalaSuite, runtimeJavaSuite, or the integration testSuite command.

By running guardrail, then attempting to compile the generated code, then running integration tests against the generated code, we can ensure quality.

Adding a new swagger spec

Adding new specifications is accomplished by:

• creating a file in modules/sample/src/main/resources
• adding an entry in exampleCases defined in build.sbt. The available flags are largely undocumented, so reading the parser is necessary.

val exampleCases: List[ExampleCase] = List(
  ExampleCase(sampleResource("additional-properties.yaml"), "additionalProperties"),
  ExampleCase(sampleResource("petstore.json"), "examples").args("--import", "support.PositiveLong"),
  ExampleCase(sampleResource("polymorphism-nested.yaml"), "polymorphismNested").frameworks(Set("akka-http", "http4s"))
)

• First argument has to point to the newly added specification file. sampleResource looks up the specification in modules/sample/src/main/resources
• Second argument defines what package to put the specification into (For regression tests, issues.issue1234)
• .args(...) is variadic, and concatenates the specified args directly to the end of your command
• .frameworks(...) is the set of frameworks that this file should be run against

Adding tests

Define your tests in ./modules/sample-*/src/test/scala make sure to use imports corresponding the previously defined packageName

Running the tests

Use the runtimeSuite command inside of an SBT session to run code generation and execute the tests

Resources

• Scalameta Quasiquotes: https://github.com/scalameta/scalameta/blob/master/notes/quasiquotes.md