Override anything in either the swagger spec in comment or the base swagger spec file (swagger.yml or swagger.json in your conf)

Day-to-day usage

For installation/get-started see the next section.

A simple example

In a cards.routes which is referenced in routes as

-> /api/cards cards.Routes

You can write the following swagger spec in comment (This example is in yml, but json is also supported). The comment has to start and end with ###.

If you don't write any comment here the endpoint is still going to be picked up by play-swagger, the parameters will be included but there will not be any response format.
This allows newly added endpoints to be automatically included in swagger with some basic information.

Note that everything in the comment is just standard swagger definition, and it $refs to a case class CardCreated, which is defined in a Protocol object, and it references another case class Card. Here is the source code:

This will generate the path with summary, tags, parameters and a response with schema defined, which comes from the comments and case class reflection.
It also recursively generates definitions from your case class.
These schemas assumes that you are using a simple Json.format[CardCreated] to generate the json response out of this class.
If not, you will have to write the definition yourself in the base swagger spec and reference it here at the endpoint
(give it a different name than the full package name though, play-swagger will try to generate definitions for any $ref that starts with the domain package name).

The result swagger specs will look like:

Get Started

In short you need to create a controller that uses the library to generate the swagger spec and make it available as an endpoint.
Then you just need to have a swagger UI instance to consumer that swagger spec.

Step 1

Step 2

Play swagger is just a library that generates a swagger spec json for you.
You can do anything you want with that json object (e.g. save it to a file), but the most common usage would be serving it in an endpoint in your play app.
Here is how:
Add a controller to your Play app that serves the swagger spec

classApiSpecs@Inject() (router: Router, cached: Cached) extendsController {
implicitvalcl= getClass.getClassLoader
// The root package of your domain classes, play-swagger will automatically generate definitions when it encounters class references in this package.// In our case it would be "com.iheart", play-swagger supports multiple domain package namesvaldomainPackage="YOUR.DOMAIN.PACKAGE"valsecondDomainPackage="YOUR.OtherDOMAIN.PACKAGE"privatelazyvalgenerator=SwaggerSpecGenerator(domainPackage, secondDomainPackage)
defspecs= cached("swaggerDef") { //it would be beneficial to cache this endpoint as we do here, but it's not required if you don't expect much traffic. Action { _ ⇒Ok(generator.generate(router.documentation))
}
}
}

Then you should be able to open the swagger ui at
http://localhost:9000/docs/swagger-ui/index.html?url=/docs/swagger.json

How to contribute

If you have any questions/bug reports, please submit an issue on github.
With good unit tests coverage, it's pretty easy to add/modify this library as well.
Code contribution are more than welcome. Make sure that your code is tested and submit the pull request!

FAQ

How to override?

To override any of the automatically generated field, you just need to write the same part in your comment or base swagger spec file.

How to hide an endpoint?

If you don't want an end point to be included, add ### NoDocs ### in front of it
e.g.