Swagger Doc

WORK IN PROGRESS

It's all very hard coded and not well named as this is draft 1 and I'm learning SBT/Scala as I go. It generates Swagger 2.0 JSON.

Intro

This project allows you to generate swagger json from Akka Http tests. It's inspired by https://github.com/kodemaniak/akka-http-restdoc which creates some generic documentation from your tests.

It has 2 components you need:

• An sbt plugin swagger-doc to run after tests have completed to generate the single swagger json file
• A trait for running Akka Http tests

Trait Example

Add the dependency:

"com.ksquared" %% "swagger-doc-akka" % "0.1"

Then write a test!

It currently depends on a RootJsonFormat instance to be in scope to convert the response body to an instance to inspect. This is an implicit param to the perform method which also needs the return type of the body.

import akka.http.scaladsl.testkit.ScalatestRouteTest
import org.scalatest.{Matchers, WordSpec}
import com.ksquared.swaggerdoc.akka.AkkaHttpDoc

class RoutesSpec extends WordSpec with Matchers
    with ScalatestRouteTest with AkkaHttpDoc {

    "the route" should {
        "post some things" in {
            val body = SomeBody("123")
            setup(Post("/some/url", body)
                .perform[Assertion, PostResponse]("some route") {
                  status shouldEqual OK
                  // rest of assertions
                }
        }
        
        "post some things to a parameterised url" in {
            val body = SomeBody("123")
            setup(Post("/some/url/1234", body, ".*\\/some/url/([0-9]{4})$".r("theId"))
                .perform[Assertion, PostResponse]("some route") {
                  status shouldEqual OK
                  // rest of assertions
                }
        }
        
        "get some things" in {
            setup(Get("/some/url/3456", ".*([0-9]*)".r("anId")
                .perform[Assertion, SomeItemResponse]("Get some item") {
                    status shouldEqual OK
                    // rest of assertions
                }
        }
    }
}

Mixin the AkkaHttpDoc and use the setup function for requests.

Urls with parameters in them:

setup(req: HttpRequest, pathRegex: Regex)

The regular expression should contain named groups to allow for clearer documentation.

setup(Get("/some/url/123456/nickname/12345"), ".*([0-9]{6})\\/nickname\\/([0-9]{5})".r("userId", "nickname"))

Plugin Example

In plugins.sbt

addSbtPlugin("com.ksquared" % "swagger-doc-generator" % "0.1")

The swagger-doc command will automatically become available.

You can configure the following properties on the swaggerDocConfig settings key.

Property name	Value type	Default value	Description
title	String	Test	The title to use for the documentation
baseUrl	String	/	The base url all api requests should be served from
apiVersion	String	0.0.1	Your api version
output	String	cwd + "/restdoc/generated"	Where to save the final json file to
input	String	cwd + "/restdoc/generated"	The location the json files generated by each test should live

Integrate with Swagger UI

In index.html of Swagger UI modify the creation of the SwaggerUI config and set the url to wherever you want to serve the swagger.json from.

window.swaggerUi = new SwaggerUi({ url: '/swagger.json', dom_id: "swagger-ui-container" })

TODO

• Figure out a friendlier way to do GET/DELETE requests
• Optional parameters

Building the project

sbt compile

Or a specific project:

sbt plugin/compile

To set a specific scala version:

sbt '++ 2.11.8 models/compile models/publishLocal