#166: Add documentation to tapiro (closes #166)

build.sbt

@@ -176,6 +176,9 @@ lazy val docs = project
     moduleName := "retro-docs",
     libraryDependencies ++= docsDependencies,
     mdocVariables := Map(
+      "CIRCE_VERSION" -> V.circe,
+      "AKKA_HTTP_VERSION" -> V.akkaHttp,
+      "TAPIR_VERSION" -> V.tapir,
       "TOCTOC_SNAPSHOT_VERSION" -> version.in(toctocCore).value,
       "TOCTOC_STABLE_VERSION" -> version.in(toctocCore).value.replaceFirst("\\+.*", ""),
       "ENUMERO_SNAPSHOT_VERSION" -> version.in(enumeroCore).value,

docs/tapiro/installation.md

@@ -56,9 +56,9 @@ The generated code comes with library dependencies.
 In case akka-http version is used:
 ```scala
 val V = new {
-  val circe = "0.9.1"
-  val tapir = "0.12.19"
-  val akkaHttp = "10.1.11"
+  val circe = "@CIRCE_VERSION@"
+  val tapir = "@TAPIR_VERSION@"
+  val akkaHttp = "@AKKA_HTTP_VERSION@"
 }
 
 val tapiroDependencies = Seq(
@@ -74,8 +74,8 @@ In case http4s is used:
 
 ```scala
 val V = new {
-  val circe = "0.9.1"
-  val tapir = "0.12.19"
+  val circe = "@CIRCE_VERSION@"
+  val tapir = "@TAPIR_VERSION@"
 }
 
 val tapiroDependencies = Seq(

docs/tapiro/introduction.md

@@ -29,18 +29,53 @@ For each controller tapiro generates two files:
 - `CatsEndpoints.scala` containing the HTTP api description using https://tapir-scala.readthedocs.io/
 - `CatsHttp4sEndpoints.scala` or `CatsAkkaHttpEndpoints.scala` depeneding on the HTTP server the user is using.
 
-The resulting routes can be simply used like this (http4s example):
-```scala
-val routes = CatsHttp4sEndpoints.routes(catsImplementation)
-
-override def run(args: List[String]): IO[ExitCode] =
-  BlazeServerBuilder[IO]
-    .bindHttp(port, host)
-    .withHttpApp(routes.orNotFound)
-    .serve
-    .compile
-    .drain
-    .as(ExitCode.Success)
+## Complete Example
+
+Here you have an example implementation of the `Cats` controller definied in the previous section:
+
+```scala mdoc
+import cats.effect._
+
+class CatsImpl[F[_]](implicit F: Sync[F]) extends Cats[F, String] {
+  override def findCutestCat(): F[Either[Error, Cat]] = F.delay(Right(Cat("Cheshire")))
+  override def doSomethingWithTheCat(catId: Int, token: String): F[Either[Error, Unit]] = F.delay(Right(()))
+}
+
+
+```
+
+Here you have the autogenerated magic fromo tapiro (This is the content of `CatsHttp4sEndpoints.scala` it will be autogenerated).
+
+```scala mdoc
+import org.http4s.HttpRoutes
+
+// ---- begins autogenerated code
+object CatsHttp4sEndpoints {
+  def routes(controller: Cats[IO, String]): HttpRoutes[IO] = ???
+}
+// ---- ends autogenerated code
+```
+
+Here is how to run the server:
+
+```scala mdoc
+import org.http4s.server.blaze._
+import org.http4s.implicits._
+import cats.implicits._
+
+object Main extends IOApp {
+  val catsImpl = new CatsImpl[IO]()
+  val routes = CatsHttp4sEndpoints.routes(catsImpl)
+
+  override def run(args: List[String]): IO[ExitCode] =
+    BlazeServerBuilder[IO]
+      .bindHttp(8080, "localhost")
+      .withHttpApp(routes.orNotFound)
+      .serve
+      .compile
+      .drain
+      .as(ExitCode.Success)
+}
 ```
 
 The resulting server can be queried as follows:

docs/tapiro/migrate.md

@@ -11,10 +11,10 @@ Here is a checklist of what you need to do:
 1. Install the plugin (as described in the [guide](installation.md))
 2. Configure your `build.sbt` (as described in the [guide](installation.md))
 3. Add `AuthToken` type parameter to controllers
-    `trait AccountController` -> `trait AccountController[AuthToken]`
+    `trait AccountController[F]` -> `trait AccountController[F[_], AuthToken]`
 4. Modify controllers so that wiro `Auth` is replaced with AuthToken and move as last argument
     `def read(token: Auth, arg: Int)` -> `def read(arg: Int, token: AuthToken)`
-5. Add `**/*Endpoints.scala linguist-generated` to repository's `.gitattributes` to hide tapiro generated code from github diff's
+5. Add `**/*Endpoints.scala linguist-generated` to repository's `.gitattributes` to automatically collapse tapiro generated code in GitHub diffs
 6. Add required codecs
 This is a valid codec for wiro.Auth:
 
@@ -39,4 +39,4 @@ def encodeAuth(auth: Auth): String = auth.token
 ```
 7. Run `sbt tapiro`
 
-Using `Server.AkkaHttp` the resulting routes can be added to wiro as custom routes.
+Using `Server.AkkaHttp` the resulting routes can be added to wiro as custom routes.

project/Dependencies.scala

@@ -82,6 +82,9 @@ object Dependencies {
   val pprint = "com.lihaoyi" %% "pprint" % V.pprint
   val sbtLogging = "org.scala-sbt" %% "util-logging" % V.sbtLogging
   val tapir = "com.softwaremill.sttp.tapir" %% "tapir-core" % V.tapir
+  val tapirJsonCirce = "com.softwaremill.sttp.tapir" %% "tapir-json-circe" % V.tapir
+  val tapirCore = "com.softwaremill.sttp.tapir" %% "tapir-core" % V.tapir
+  val tapirHttp4s = "com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % V.tapir
 
   val enumeroDependencies = List(
     scalatest,
@@ -193,7 +196,10 @@ object Dependencies {
 
   val docsDependencies = List(
     plantuml,
-    tapir
+    tapir,
+    tapirJsonCirce,
+    tapirCore,
+    tapirHttp4s
   )
 
 }