add documentation

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# How To Contribute
+
+## Architecture
+
+This repository contains these components:
+
+* `sbt-plugin` - The main sbt plugin
+* `runner` - The runtime entrypoint, cross-compiled for different Play and Scala versions
+* `test-plugin` - Extra testing utilities used in `scripted` tests (not published)
+
+Here's how this plugin works:
+
+1. The sbt plugin picks an appropriate runner based on the current application's Play and Scala version
+1. The sbt plugin constructs a ClassLoader containing the application's classpath and the runner's classpath
+1. The sbt plugin calls the runner's entrypoint
+1. The runner generates a Swagger spec, by reflecting over the application's routes and models
+1. The sbt plugin adds the generated `swagger.json` as a managed resource
+
+## Running tests
+
+* `test` – Runs the unit tests
+* `scripted` – Runs [sbt script tests](http://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html)

README.md

@@ -1,24 +1,50 @@
 # sbt-swagger-play
 
-An sbt AutoPlugin
+[![build](https://github.com/dwickern/sbt-swagger-play/workflows/build/badge.svg)](https://github.com/dwickern/sbt-swagger-play/actions)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.dwickern/sbt-swagger-play_2.12_1.0/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.dwickern/sbt-swagger-play_2.12_1.0)
+
+An sbt plugin which runs [swagger-play](https://github.com/dwickern/swagger-play) as part of your build.
+
+Advantages:
+* Your application has no runtime dependency on swagger-play or swagger-core (only on swagger-annotations).
+* Your application serves `swagger.json` as a static asset.
+* This plugin optionally includes some extra validation for common Swagger annotation mistakes
 
 ## Usage
 
-This plugin requires sbt 1.0.0+
+In `project/plugins.sbt`:
+```sbt
+addSbtPlugin("com.github.dwickern" % "sbt-swagger-play" % "0.1")
+```
+
+In `build.sbt`:
+```sbt
+libraryDependencies += "io.swagger" % "swagger-annotations" % "1.6.1"
+```
+
+In `conf/routes`:
+```
+GET     /swagger.json        controllers.Assets.at(path="/public", file="swagger.json")
+```
+
+That's it. Now you can annotate your REST endpoints and models with Swagger annotations.
+Also make sure to set up your [application.conf](https://github.com/dwickern/swagger-play#applicationconf---config-options).
 
-### Testing
+## Migrating from swagger-play
 
-Run `test` for regular unit tests.
+If you're already using swagger-play as a dependency in your application, this plugin is meant as a drop-in replacement.
 
-Run `scripted` for [sbt script tests](http://www.scala-sbt.org/1.x/docs/Testing-sbt-plugins.html).
+In `conf/application.conf`, remove any reference to `SwaggerModule`:
+```
+# REMOVE:
+play.modules.enabled += "play.modules.swagger.SwaggerModule"
+```
 
-### Publishing
+In `conf/routes`, remove any reference to `ApiHelpController` and instead serve `swagger.json` as a static asset:
+```
+# REMOVE:
+GET     /swagger.json        controllers.ApiHelpController.getResources
 
-1. publish your source to GitHub
-2. [create a bintray account](https://bintray.com/signup/index) and [set up bintray credentials](https://github.com/sbt/sbt-bintray#publishing)
-3. create a bintray repository `sbt-plugins` 
-4. update your bintray publishing settings in `build.sbt`
-5. `sbt publish`
-6. [request inclusion in sbt-plugin-releases](https://bintray.com/sbt/sbt-plugin-releases)
-7. [Add your plugin to the community plugins list](https://github.com/sbt/website#attention-plugin-authors)
-8. [Claim your project an Scaladex](https://github.com/scalacenter/scaladex-contrib#claim-your-project)
+# ADD:
+GET     /swagger.json        controllers.Assets.at(path="/public", file="swagger.json")
+```