softwaremill · adamw · Jul 10, 2024 · Jul 8, 2024 · Jul 8, 2024 · Jul 8, 2024
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -68,6 +68,11 @@ jobs:
         sudo apt-get update
         sudo apt-get install libidn2-dev libcurl3-dev
         echo "STTP_NATIVE=1" >> $GITHUB_ENV
+    - name: Install scala-cli
+      if: matrix.target-platform == 'JVM' && matrix.java == '21' && matrix.scala-version == '3'
+      uses: VirtusLab/scala-cli-setup@main
+      with:
+        jvm: '' # needed because scala-cli-setup otherwise forces the installation of their default JVM (17)
     - name: Enable Loom-specific modules
       if: matrix.java == '21'
       run: echo "ONLY_LOOM=1" >> $GITHUB_ENV
@@ -76,6 +81,9 @@ jobs:
     - name: Compile documentation
       if: matrix.target-platform == 'JVM' && matrix.java == '21'
       run: sbt $SBT_JAVA_OPTS -v compileDocumentation
+    - name: Verify that examples compile using Scala CLI
+      if: matrix.target-platform == 'JVM' && matrix.java == '21' && matrix.scala-version == '3'
+      run: sbt $SBT_JAVA_OPTS -v "project examples3" verifyExamplesCompileUsingScalaCli
     - name: Test
       if: matrix.target-platform == 'JVM' && matrix.scala-version == '2.12'
       uses: nick-fields/retry@v2

diff --git a/build.sbt b/build.sbt
@@ -29,6 +29,7 @@ val ideScalaVersion = scala3
 lazy val clientTestServerPort = settingKey[Int]("Port to run the client interpreter test server on")
 lazy val startClientTestServer = taskKey[Unit]("Start a http server used by client interpreter tests")
 lazy val generateMimeByExtensionDB = taskKey[Unit]("Generate the mime by extension DB")
+lazy val verifyExamplesCompileUsingScalaCli = taskKey[Unit]("Verify that each example compiles using Scala CLI")
 
 concurrentRestrictions in Global ++= Seq(
   Tags.limit(Tags.Test, 1),
@@ -63,6 +64,8 @@ val commonSettings = commonSmlBuildSettings ++ ossPublishSettings ++ Seq(
   Test / unmanagedSourceDirectories ++= versionedScalaSourceDirectories((Test / sourceDirectory).value, scalaVersion.value),
   updateDocs := Def.taskDyn {
     val files1 = UpdateVersionInDocs(sLog.value, organization.value, version.value)
+    // for the root project the sourceDirectory points to src, so ../ will point to the root directory of the project
+    GenerateListOfExamples(sLog.value, sourceDirectory.value.getParentFile)
     Def.task {
       (documentation.jvm(documentationScalaVersion) / mdoc).toTask("").value
       files1 ++ Seq(file("generated-doc/out"))
@@ -2046,7 +2049,8 @@ lazy val examples: ProjectMatrix = (projectMatrix in file("examples"))
       logback
     ),
     publishArtifact := false,
-    Compile / run / fork := true
+    Compile / run / fork := true,
+    verifyExamplesCompileUsingScalaCli := VerifyExamplesCompileUsingScalaCli(sLog.value, sourceDirectory.value)
   )
   .jvmPlatform(scalaVersions = List(examplesScalaVersion))
   .dependsOn(

diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css
@@ -0,0 +1,42 @@
+/* general style for all example tags */
+.example-tag {
+    border-width: 1px;
+    border-radius: 9999px;
+    border-style: solid;
+    padding-left: 0.5rem;
+    padding-right: 0.5rem;
+    margin-right: 0.25rem;
+    margin-top: 0.25rem;
+    margin-bottom: 0.25rem;
+}
+
+/* different colors for specific tags */
+.example-effects {
+    color: rgb(193 21 116);
+    background-color: rgb(253 242 250);
+    border-color: rgb(252 206 238);
+}
+
+.example-json {
+    color: rgb(185 56 21);
+    background-color: rgb(254 246 238);
+    border-color: rgb(249 219 175);
+}
+
+.example-server {
+    color: rgb(6 118 71);
+    background-color: rgb(236 253 243);
+    border-color: rgb(169 239 197);
+}
+
+.example-docs {
+    color: rgb(52 64 84);
+    background-color: rgb(249 250 251);
+    border-color: rgb(234 236 240);
+}
+
+.example-client {
+    color: rgb(6 89 134);
+    background-color: rgb(240 249 255);
+    border-color: rgb(185 230 254);
+}
diff --git a/doc/adopters.md b/doc/adopters.md
@@ -0,0 +1,43 @@
+# Adopters
+
+Is your company already using tapir? We're continually expanding the "adopters" section in the documentation; the more the merrier! It would be great to feature your company's logo, but in order to do that, we'll need written permission to avoid any legal misunderstandings.
+
+Please email us at [[email protected]](mailto:[email protected]) from your company's email with a link to your logo (if we can use it, of course!) or with details who to kindly ask for permission to feature the logo in tapir's documentation. We'll handle the rest.
+
+Thank you!
+
+<div style="display: flex; justify-content: space-between; align-items: center;">
+<a href="https://www.adobe.com" title="Adobe"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/adobe.png" alt="Adobe" width="160"/></a>
+<a href="https://swisscom.com" title="Swisscom"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/swisscom.svg" alt="Swisscom" width="160"/></a>
+<a href="https://swissborg.com" title="Swissborg"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/swissborg.png" alt="Swissborg" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center;">
+<a href="https://kaizo.com" title="Kaizo"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/kaizo.png" alt="Kaizo" width="160"/></a>
+<a href="https://www.process.st/" title="Process Street"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/process_street.png" alt="Process Street" width="100"/></a>
+<a href="https://tranzzo.com" title="Tranzzo"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/tranzzo.svg" alt="Tranzzo" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center; margin-top:10px;">
+<a href="https://www.kelkoogroup.com" title="Kelkoo group"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/kelkoogroup.png" alt="Kelkoo group" width="160"/></a>
+<a href="https://www.softwaremill.com/" title="SoftwareMill"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/softwaremill.png" alt="SoftwareMill" width="160"/></a>
+<a href="https://www.carvana.com" title="Carvana"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/carvana.svg" alt="Carvana" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center;">
+<a href="https://www.moneyfarm.com" title="Moneyfarm"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/moneyfarm.png" alt="Moneyfarm" width="160"/></a>
+<a href="https://www.ocadogroup.com/about-us/ocado-technology/" title="Ocado Technology"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/ocado.png" alt="Ocado" width="160"/></a>
+<a href="https://www.wegtam.com" title="Wegtam"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/wegtam.svg" alt="Wegtam" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center; height: 100px;">
+<a href="http://www.broad.app/" title="Broad"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/broad.png" alt="Broad" width="160"/></a>
+<a href="https://www.kensu.io?utm_source=github&utm_campaign=tapir"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/kensu.png" alt="Kensu" width="160"/></a>
+<a href="https://www.colisweb.com" title="Colisweb"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/colisweb.png" alt="Colisweb" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center; height: 100px;">
+<a href="http://www.iceo.co/"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/iceo.png" alt="iceo" width="160"/></a>
+<a href="http://www.dpgrecruitment.nl/"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/dpg-recruitment.svg" alt="dpg" width="160"/></a>
+<a href="https://www.hunters.security/"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/hunters.png" alt="hunters" width="160"/></a>
+</div>
+<div style="display: flex; justify-content: space-between; align-items: center; height: 100px;">
+<a href="https://www.moia.io/en"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/moia.png" alt="moia" width="160"/></a>
+<a href="https://www.pitsdatarecovery.net"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/pits.svg" alt="pits" width="100"/></a>
+<a href="https://www.hootsuite.com"><img src="https://github.com/softwaremill/tapir/raw/master/doc/adopters/hootsuite.png" alt="hootsuite" width="160"/></a>
+</div>
diff --git a/doc/conf.py b/doc/conf.py
@@ -101,6 +101,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #

diff --git a/doc/endpoint/customtypes.md b/doc/endpoint/customtypes.md
@@ -1,4 +1,4 @@
-# Custom types
+# Adding support for custom types
 
 To support a custom type, you'll need to provide an implicit `Codec` for that type, or the components to create such
 a codec. 

diff --git a/doc/endpoint/integrations.md b/doc/endpoint/integrations.md
@@ -1,4 +1,4 @@
-# Datatypes integrations
+# Third-party datatype libraries integrations
 
 ```{note}
 Note that the codecs defined by the tapir integrations are used only when the specific types (e.g. enumerations) are 

diff --git a/doc/examples.md b/doc/examples.md
@@ -1,35 +1,15 @@
-# Examples
+# Examples by category
 
-The [examples](https://github.com/softwaremill/tapir/tree/master/examples/src/main/scala/sttp/tapir/examples) sub-project contains a number of runnable tapir usage examples, using various interpreters and showcasing different features.
+The Tapir repository contains a number of how-to guides. If you're missing an example for your use-case, please let us
+know by [reporting an issue](https://github.com/softwaremill/tapir)!
 
-## Generate a tapir project
+Each example is fully self-contained and can be run using [scala-cli](https://scala-cli.virtuslab.org) (you just need
+to copy the content of the file, apart from scala-cli, no additional setup is required!). Hopefully this will make
+experimenting with Tapir as frictionless as possible!
 
-You can generate a simple tapir-based project using chosen features, build tool and effect system using [adopt-tapir](https://adopt-tapir.softwaremill.com).
+```{eval-rst}
+.. include:: includes/examples_list.md
+   :parser: markdown
+```
 
-Alternatively, you can generate a stub of a tapir-based application directly from the command line with `sbt new softwaremill/tapir.g8`.
 
-## Third-party examples
-
-* http4s interpreter: [todo-backend](https://github.com/lolgab/snunit-tapir-example)
-* quickstart using http4s: [a gitter8 template](https://codeberg.org/wegtam/http4s-tapir.g8). A new project can be created using: `sbt new https://codeberg.org/wegtam/http4s-tapir.g8.git`
-* Scala Native application, [using Nginx Unit](https://github.com/lolgab/snunit-tapir-example).
-
-## Blogs, articles
-
-* [Migrating from Akka HTTP to tapir](https://softwaremill.com/migrating-from-akka-http-to-tapir/)
-* [Benchmarking Tapir: Part 1](https://softwaremill.com/benchmarking-tapir-part-1/)
-* [Benchmarking Tapir: Part 2](https://softwaremill.com/benchmarking-tapir-part-2/)
-* [Tapir 1.0 released](https://softwaremill.com/tapir-1-0-released/)
-* [Security improvements in tapir 0.19](https://softwaremill.com/security-improvements-in-tapir-0-19/)
-* [Tapir serverless: a proof of concept](https://blog.softwaremill.com/tapir-serverless-a-proof-of-concept-6b8c9de4d396)
-* [Designing tapir's WebSockets support](https://blog.softwaremill.com/designing-tapirs-websockets-support-ff1573166368)
-* [Three easy endpoints](https://blog.softwaremill.com/three-easy-endpoints-a6cbd52b0a6e)
-* [tAPIr's Endpoint meets ZIO's IO](https://blog.softwaremill.com/tapirs-endpoint-meets-zio-s-io-3278099c5e10)
-* [Describe, then interpret: HTTP endpoints using tapir](https://blog.softwaremill.com/describe-then-interpret-http-endpoints-using-tapir-ac139ba565b0)
-* [Functional pancakes](https://blog.softwaremill.com/functional-pancakes-cf70023f0dcb)
-
-## Videos
-
-* [ScalaLove 2020: Your HTTP endpoints are data, as well!](https://www.youtube.com/watch?v=yuQNgZgSFIc&t=944s)
-* [Scalar 2020: A Functional Scala Stack For 2020](https://www.youtube.com/watch?v=DGlkap5kzGU)
-* [ScalaWorld 2019: Designing Programmer-Friendly APIs](https://www.youtube.com/watch?v=I3loMuHnYqw)
diff --git a/doc/external.md b/doc/external.md
@@ -0,0 +1,33 @@
+# Articles, videos, other examples
+
+## Generate a tapir project
+
+You can generate a simple tapir-based project using chosen features, build tool and effect system using [adopt-tapir](https://adopt-tapir.softwaremill.com).
+
+Alternatively, you can generate a stub of a tapir-based application directly from the command line with `sbt new softwaremill/tapir.g8`.
+
+## Third-party examples
+
+* http4s interpreter: [todo-backend](https://github.com/lolgab/snunit-tapir-example)
+* quickstart using http4s: [a gitter8 template](https://codeberg.org/wegtam/http4s-tapir.g8). A new project can be created using: `sbt new https://codeberg.org/wegtam/http4s-tapir.g8.git`
+* Scala Native application, [using Nginx Unit](https://github.com/lolgab/snunit-tapir-example).
+
+## Blogs, articles
+
+* [Migrating from Akka HTTP to tapir](https://softwaremill.com/migrating-from-akka-http-to-tapir/)
+* [Benchmarking Tapir: Part 1](https://softwaremill.com/benchmarking-tapir-part-1/)
+* [Benchmarking Tapir: Part 2](https://softwaremill.com/benchmarking-tapir-part-2/)
+* [Tapir 1.0 released](https://softwaremill.com/tapir-1-0-released/)
+* [Security improvements in tapir 0.19](https://softwaremill.com/security-improvements-in-tapir-0-19/)
+* [Tapir serverless: a proof of concept](https://blog.softwaremill.com/tapir-serverless-a-proof-of-concept-6b8c9de4d396)
+* [Designing tapir's WebSockets support](https://blog.softwaremill.com/designing-tapirs-websockets-support-ff1573166368)
+* [Three easy endpoints](https://blog.softwaremill.com/three-easy-endpoints-a6cbd52b0a6e)
+* [tAPIr's Endpoint meets ZIO's IO](https://blog.softwaremill.com/tapirs-endpoint-meets-zio-s-io-3278099c5e10)
+* [Describe, then interpret: HTTP endpoints using tapir](https://blog.softwaremill.com/describe-then-interpret-http-endpoints-using-tapir-ac139ba565b0)
+* [Functional pancakes](https://blog.softwaremill.com/functional-pancakes-cf70023f0dcb)
+
+## Videos
+
+* [ScalaLove 2020: Your HTTP endpoints are data, as well!](https://www.youtube.com/watch?v=yuQNgZgSFIc&t=944s)
+* [Scalar 2020: A Functional Scala Stack For 2020](https://www.youtube.com/watch?v=DGlkap5kzGU)
+* [ScalaWorld 2019: Designing Programmer-Friendly APIs](https://www.youtube.com/watch?v=I3loMuHnYqw)
diff --git a/doc/generate.md b/doc/generate.md
@@ -0,0 +1,21 @@
+# Generate a Tapir project
+
+Not sure how to start?
+
+We recommend the defaults below (Direct-style stack & Netty server); this requires Java 21+. Otherwise, 
+you might also try the Future stack + Netty, which works on Java 11+.
+
+If you'd like to include a JSON endpoint, using the [jsoniter](https://github.com/plokhotnyuk/jsoniter-scala) library
+might a good choice!
+
+```{eval-rst}
+.. raw:: html
+
+   <iframe
+     frameborder=0
+     sandbox="allow-scripts allow-same-origin allow-forms allow-downloads allow-popups"
+     src="https://adopt-tapir.softwaremill.com/embedded-form"
+     width="100%"
+     height="603"
+   ></iframe>
+```