Merge branch 'master' into feat/add-zio-multipart-body-support

.github/labeler.yml

@@ -6,9 +6,11 @@ labels:
       - "build.sbt"
       - "project/Versions.scala"
       - "project/plugins.sbt"
+      - "examples\\/src\\/main\\/scala\\/.*"
   - label: "dependency"
     authors: ["softwaremill-ci"]
     files:
       - "build.sbt"
       - "project/Versions.scala"
       - "project/plugins.sbt"
+      - "examples\\/src\\/main\\/scala\\/.*"

.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
@@ -208,15 +216,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      # count number of files changed
-      - name: Count number of files changed
-        id: count-changed-files
-        run: |
-               N=$(git diff --name-only -r HEAD^1 HEAD | wc -w)
-               echo "changed_files_num=$N" >> $GITHUB_OUTPUT
       - name: Launch labeler
-        # skip if more than one file changed
-        if: steps.count-changed-files.outputs.changed_files_num == 1
         uses: srvaroa/labeler@master
         env:
           GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

README.md

@@ -131,7 +131,7 @@ tapir documentation is available at [tapir.softwaremill.com](http://tapir.softwa
 Add the following dependency:
 
 ```sbt
-"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.10.12"
+"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.10.13"
 ```
 
 Then, import:

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),
@@ -65,6 +66,9 @@ val commonSettings = commonSmlBuildSettings ++ ossPublishSettings ++ Seq(
     val files1 = UpdateVersionInDocs(sLog.value, organization.value, version.value)
     Def.task {
       (documentation.jvm(documentationScalaVersion) / mdoc).toTask("").value
+      // Generating the list only after mdoc is done (as it overrides what's in generated_doc)
+      // 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)
       files1 ++ Seq(file("generated-doc/out"))
     }
   }.value,
@@ -920,8 +924,8 @@ lazy val jsoniterScala: ProjectMatrix = (projectMatrix in file("json/jsoniter"))
   .settings(
     name := "tapir-jsoniter-scala",
     libraryDependencies ++= Seq(
-      "com.github.plokhotnyuk.jsoniter-scala" %%% "jsoniter-scala-core" % "2.30.4",
-      "com.github.plokhotnyuk.jsoniter-scala" %%% "jsoniter-scala-macros" % "2.30.4" % Test,
+      "com.github.plokhotnyuk.jsoniter-scala" %%% "jsoniter-scala-core" % "2.30.7",
+      "com.github.plokhotnyuk.jsoniter-scala" %%% "jsoniter-scala-macros" % "2.30.7" % Test,
       scalaTest.value % Test
     )
   )
@@ -2046,7 +2050,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(

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);
+}

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>

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.
 #

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. 

doc/endpoint/enumerations.md

@@ -274,7 +274,7 @@ case class Foo(aOrB: "a" | "b", optA: Option["a"]) derives Schema
 
 ### Creating an enum schema by hand
 
-Creating an enumeration [schema](schema.md) by hand is exactly the same as for any other type. The only difference
+Creating an enumeration [schema](schemas.md) by hand is exactly the same as for any other type. The only difference
 is that an enumeration [validator](validation.md) has to be added to the schema.
 
 ## Next

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 

doc/endpoint/json.md

@@ -53,7 +53,7 @@ To use [Circe](https://github.com/circe/circe), add the following dependency to
 "com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonCirce` trait, see [MyTapir](../mytapir.md)):
+Next, import the package (or extend the `TapirJsonCirce` trait, see [MyTapir](../other/mytapir.md)):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.circe.*
@@ -125,7 +125,7 @@ To use [µPickle](http://www.lihaoyi.com/upickle/) add the following dependency
 "com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonuPickle` trait, see [MyTapir](../mytapir.md) and add `TapirJsonuPickle` not `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonuPickle` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonuPickle` not `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.upickle.*
@@ -165,7 +165,7 @@ For **Play 2.9** use:
 "com.softwaremill.sttp.tapir" %% "tapir-json-play29" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonPlay` trait, see [MyTapir](../mytapir.md) and add `TapirJsonPlay` not `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonPlay` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonPlay` not `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.play.*
@@ -181,7 +181,7 @@ To use [Spray JSON](https://github.com/spray/spray-json) add the following depen
 "com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonSpray` trait, see [MyTapir](../mytapir.md) and add `TapirJsonSpray` not `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonSpray` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonSpray` not `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.spray.*
@@ -197,7 +197,7 @@ To use [Tethys JSON](https://github.com/tethys-json/tethys) add the following de
 "com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonTethys` trait, see [MyTapir](../mytapir.md) and add `TapirJsonTethys` not `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonTethys` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonTethys` not `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.tethysjson.*
@@ -213,7 +213,7 @@ To use [Jsoniter-scala](https://github.com/plokhotnyuk/jsoniter-scala) add the f
 "com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "@VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJsonJsoniter` trait, see [MyTapir](../mytapir.md) and add `TapirJsonJsoniter` not `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonJsoniter` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonJsoniter` not `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.jsoniter.*
@@ -237,7 +237,7 @@ And one of the implementations:
 "org.json4s" %% "json4s-jackson" % "@JSON4S_VERSION@"
 ```
 
-Next, import the package (or extend the `TapirJson4s` trait, see [MyTapir](../mytapir.md) and add `TapirJson4s` instead of `TapirCirceJson`):
+Next, import the package (or extend the `TapirJson4s` trait, see [MyTapir](../other/mytapir.md) and add `TapirJson4s` instead of `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.json4s.*
@@ -259,7 +259,7 @@ To use [zio-json](https://github.com/zio/zio-json), add the following dependency
 ```scala
 "com.softwaremill.sttp.tapir" %% "tapir-json-zio" % "@VERSION@"
 ```
-Next, import the package (or extend the `TapirJsonZio` trait, see [MyTapir](../mytapir.md) and add `TapirJsonZio` instead of `TapirCirceJson`):
+Next, import the package (or extend the `TapirJsonZio` trait, see [MyTapir](../other/mytapir.md) and add `TapirJsonZio` instead of `TapirCirceJson`):
 
 ```scala mdoc:compile-only
 import sttp.tapir.json.zio.*

doc/endpoint/schemas.md

@@ -119,7 +119,7 @@ the union type, as it's not possible to generate a runtime check for the generic
 ### Derivation for string-based constant union types
 e.g. `type AorB = "a" | "b"`
 
-See [enumerations](enumerations.md#scala-3-string-based-constant-union-types-to-enum) on how to use string-based unions of constant types as enums.
+See [enumerations](enumerations.html#scala-3-string-based-constant-union-types-to-enum) on how to use string-based unions of constant types as enums.
 
 ## Configuring derivation
 

doc/endpoint/security.md

@@ -31,7 +31,7 @@ base64-encoded username/password combination, use: `basic[UsernamePassword]`.
 as a string, use: `bearer[String]`.
 * `auth.oauth2.authorizationCode(authorizationUrl, scopes, tokenUrl, refreshUrl): EndpointInput[String]`: creates an 
 OAuth2 authorization using authorization code - sign in using an auth service (for documentation, requires defining also 
-the `oauth2-redirect.html`, see [Generating OpenAPI documentation](..docs/openapi.md))
+the `oauth2-redirect.html`, see [Generating OpenAPI documentation](../docs/openapi.md))
 
 ## Authentication challenges
 

doc/examples.md

@@ -1,35 +1,18 @@
-# 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).
+Examples are tagged with the stack being used (Direct-style, cats-effect, ZIO, Future), server implementation, generated
+documentation format etc.
 
-Alternatively, you can generate a stub of a tapir-based application directly from the command line with `sbt new softwaremill/tapir.g8`.
+```{eval-rst}
+.. include:: includes/examples_list.md
+   :parser: markdown
+```
 
-## 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)