Generate OAS Specs from Tests:
Test Driven Documentation for Akka HTTP Scala

Test Driven Documentation

Your tests are already the source of truth for your API, now you can use them to generate OAS/Swagger every time you run them. This is great because:
  • Since tests are coupled to your code, the docs are updated on every commit
  • Tests are the best abstraction for defining an API contract
  • Tests document the actual behavior of your API, not how you think it works
  • You'll never write Swagger manually again

Install CLI

Optic is an open source project backed by YCombinator. It's great for documenting APIs and can output Swagger, API Clients or static documentation.
$ npm install @useoptic/cli -g 

Setup API

In order to learn your API spec, Optic needs to know:
  • How to run your API's integration tests
  • Which paths you want it to document
This configuration is defined in an optic.yml file placed in the root directory of your API repository. First navigate to your API repository:
$ cd path/to/repo
Then create an optic.yml manually or by running optic setup:init.
  id: your-api-name        # pick a slug for your API
  version: 0.1.0           # a semantic version for the API
  run_tests: npm run test  # the command that runs your tests
  paths:                   # the paths you want Optic to document
    - /self
    - /self/memberships/:teamId
    - /self/posts/:postId
Optic will only document paths that are listed in the optic.yml. Since it might take a few minutes to fill out the paths section of the file, we suggest picking 3 paths to start and adding the remaining ones at the end of the tutorial.

Using Optic with Akka HTTP

Akka HTTP projects are easy to connect to Optic using our custom middleware. In this tutorial we'll show you how to connect the Optic Documenting Middleware to your Akka HTTP API so that your integration tests document your code as they execute.


Include the following dependency in your build.sbt file:
libraryDependencies += "com.useoptic" %% "document-akka-http" % "0.2.0"

Using the Proxy Fixture

The OpticFixture is designed to work seamlessly with the Route TestKit DSL. Just wrap the Route instances you want included in your documentation like this:
import com.useoptic.akka_http.scaladsl.Document.withOptic

it("/hello responds with 'World!'") {
    Get("/hello") ~> withOptic(helloRoute) ~> check {
      assert(responseAs[String] ==  "World!")
The Optic enabled Route returned by withOptic can be reused as many times as you'd like. Here's an example of typical pattern for injecting Optic into your existing tests.
import com.useoptic.akka_http.scaladsl.Document.withOptic

val documentedHelloRoute = withOptic(helloRoute)

it("/hello responds with 'World!'") {
    Get("/hello") ~> documentedHelloRoute ~> check {
      assert(responseAs[String] ==  "World!")

it("/hello with query name=Bob responds with 'Hello Bob!'") {
    Get("/hello?name=Bob") ~> documentedHelloRoute ~> check {
      assert(responseAs[String] ==  "Hello Bob!")

Verify Integration

Before we continue, let's take a moment to make sure everything is set up properly. You can run optic setup:tests to verify that:
  • Optic's documenting middleware has been included correctly
  • the optic.yml is configured to run your API tests properly
$ optic setup:tests

  Listening for API interactions in your tests... done

  Observed >= 1 API Interactions. Your test setup is valid
All setup? Nice work! Let's document your API now.

Document the API

Now that you've added Optic to your API, you can run the document command anytime to get the current contract of the API and generate a Swagger specification.
$ optic api:document --generate oas
The OAS Spec will be generated in .optic/oas.

That's it!

If this tutorial helped you check out Optic's Website and our GitHub to learn more about our other tools.