Docs improvement

Author: chuwy

Rho.md

@@ -1,46 +1,64 @@
 # Documenting Http4s web services with rho
-Rho is a library for documenting Http4s web apis.
 
-Note: To get the generated swagger.json, you need to visit: `{https|http}://host:port/{base path if any}/swagger.json`
+Rho is a library for documenting [http4s](https://http4s.org/) web APIs.
+
+Note: To get the generated swagger.json, you need to visit: `{https|http}://host:port/{base service path if any}/swagger.json`
 
 Sample:
+
 ```scala
 val api = new RhoService[IO] {
-    "Description of api endpoint" **
-    GET / "somePath" / pathVar[Int]("someInt", "parameter description") +? paramD[String]("name", "parameter description") |>> { (someInt: Int, name: String) => {
-            Ok("result")
-        }
+    GET / "somePath" / pathVar[Int]("someInt", "parameter description") +? paramD[String]("name", "parameter description") |>> {
+      (someInt: Int, name: String) => Ok("result")
     }
 }
 ```
 
-So we start by creating a new RhoService which will be converted to an HttpService later. This RhoService will contain our api endpoints. Every api endpoint starts (optionally) with a description for that endpoint and then the implementation. We describe the HTTP method (GET/POST/DELETE etc) and then an implementation for the url endpoint.
+So we start by creating a new RhoService which will be converted to an HttpService later. This RhoService will contain our api endpoints. Every api endpoint starts (optionally, for Swagger) with a description for that endpoint and then the implementation. We describe the HTTP method (GET/POST/DELETE etc) and then an implementation for the url endpoint.
 
 You can specify and capture path or query parameters in your path. You specify a name and description (optional) for the variables. The available types that you can capture are:
 - all primitive types
-- java.util.Date (yyyy-MM-dd)
-- java.util.UUID
-- java.time.Instant (yyyy-MM-ddThh:mm:ssZ)
+- `java.util.Date` (yyyy-MM-dd)
+- `java.util.UUID`
+- `java.time.Instant` (yyyy-MM-ddThh:mm:ssZ)
 
 Checkout these methods:
 - `pathVar` functions for capturing path variables
 - `param` functions for capturing query parameters
 - `capture` functions for capturing headers
 
+Think of `|>>` as a function that "registers" new route matcher and associated action in RhoService.
+Route matcher is at lefthand-side (represented as `TypedBuilder`) and action at righthand-side is a function returning HTTP response.
+The arguments for action appear exactly as they do in the URL spec (route matcher).
+So in the sample above, `someInt` is first then `name` and so on. Optionally it can accept whole `org.http4s.Request` as first argument.
 
-Think of `|>>` as a function from url specification to an implementation which returns a Response. The arguments for `|>>` appear exactly as they do in the url spec. So in the sample above, `someInt` is first then `name` and so on.
+Apart from plain URL parameters and path, you can insert header captures and body decoders for your requests, an example:
 
-You can insert header captures and body decoders for your requests, an example:
 ```scala
+object Auth extends org.http4s.rho.AuthedContext[IO, AuthInfo]
+
 val api = new RhoService[IO] {
-    "Description of api endpoint" **
-    POST / "somePath" / pathVar[Int]("someInt", "parameter description") >>> auth ^ jsonOf[T] |>> { (someInt: Int, au: AuthInfo, body: T) => {
-            Ok("result")
-        }
+    import org.http4s.rho.swagger.syntax.io._
+    
+    "Description of api endpoint" **      // Description is optional and specific to Swagger
+    POST / "somePath" / pathVar[Int]("someInt", "parameter description") >>> Auth.auth() ^ jsonOf[IO, T] |>> {
+      (someInt: Int, au: AuthInfo, body: T) => Ok("result")
     }
 }
 ```
-`auth` captures the authentication information. We are specifying that the body is a json object for some T.
+
+`Auth.auth()` captures the authentication information.
+In order to provide authentication information:
+1. `AuthedContext` should be transformed into `HttpService`
+2. `AuthMiddleware[IO, AuthInfo]` must wrap above service
+
+```scala
+val authInfoMiddleware: org.http4s.server.AuthMiddleware[IO, AuthInfo] = ???  // Standard http4s AuthMiddleware
+val authApi = Auth.toService(api.toService())                                 // 1
+val service: org.http4s.HttpService[IO] = authInfoMiddleware.apply(authApi)   // 2
+```
+
+Also, in example above, we are specifying that the body is a json object for some `T`.
 Anything that has a `EntityDecoder` can be specified as a body decoder. In the example above `jsonOf` is an `EntityDecoder` provided by `circe`. Included decoders in Rho are:
 - binary
 - binaryChunk
@@ -59,6 +77,8 @@ case class MyClass(name: String, description: String, someBool: Boolean, tags: L
 //or
 case class MyClass(name: String, description: String, someBool: Boolean, tags: List[String], someObj: JsonObject)
 
+import org.http4s.rho.swagger.models._
+
 val myClassModel: Set[Model] = Set(
     ModelImpl(
       id = "MyClass",
@@ -101,24 +121,31 @@ val myClassModel: Set[Model] = Set(
     )
   )
 
-// register this model
-SwaggerSupport[IO].createRhoMiddleware(
-              swaggerFormats = DefaultSwaggerFormats
-                .withSerializers(typeOf[MyClass], myClassModel)
-                .withSerializers(...),
-                apiInfo = Info(
-                title = "My API",
-                version = "1.0.0",
-                description = Some("functional because who hates sleep?")
-              ),
-              basePath = "/v1".some,
-              schemes = List(Scheme.HTTPS),
-              security = List(SecurityRequirement("bearer", List())),
-              securityDefinitions = Map(
-                "bearer" -> ApiKeyAuthDefinition("Authorization", In.HEADER)
-              ))
+import org.http4s.rho.RhoMiddleware
+import org.http4s.rho.swagger.syntax.{io => ioSwagger}
+
+// Create a middleware that will transform RhoService into HttpService with attached Swagger definition
+val swaggerMiddleware: RhoMiddleware[IO] = ioSwagger.createRhoMiddleware(
+  swaggerFormats = DefaultSwaggerFormats
+    .withSerializers(typeOf[MyClass], myClassModel)
+    .withSerializers(...),
+    apiInfo = Info(
+    title = "My API",
+    version = "1.0.0",
+    description = Some("functional because who hates sleep?")
+  ),
+  basePath = "/v1".some,
+  schemes = List(Scheme.HTTPS),
+  security = List(SecurityRequirement("bearer", List())),
+  securityDefinitions = Map(
+    "bearer" -> ApiKeyAuthDefinition("Authorization", In.HEADER)
+  ))
+  
+// Create http4s HttpService
+val httpService = api.toService(swaggerMiddleware)
 ```
-Tha example above also shows how to provide basic api info and base path and security specification.
-By declaring security here we get option to add api key/token in the swagger ui.
+
+The example above also shows how to provide basic api info and base path and security specification.
+By declaring security here we get option to add api key/token in the Swagger UI.
 
 To get the generated swagger.json for this example, you would visit: `https://host:port/v1/swagger.json`