Release 1.1.3

README.md

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

generated-doc/out/client/http4s.md

@@ -3,7 +3,7 @@
 Add the dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-http4s-client" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-http4s-client" % "1.1.3"
 ```
 
 To interpret an endpoint definition as an `org.http4s.Request[F]`, import:

generated-doc/out/client/play.md

@@ -3,7 +3,7 @@
 Add the dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "1.1.3"
 ```
 
 To make requests using an endpoint definition using the [play client](https://github.com/playframework/play-ws), import:

generated-doc/out/client/sttp.md

@@ -3,7 +3,7 @@
 Add the dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "1.1.3"
 ```
 
 To make requests using an endpoint definition using the [sttp client](https://github.com/softwaremill/sttp), import:
@@ -102,7 +102,7 @@ In this case add the following dependencies (note the [`%%%`](https://www.scala-
 instead of the usual `%%`):
 
 ```scala
-"com.softwaremill.sttp.tapir" %%% "tapir-sttp-client" % "1.1.2"
+"com.softwaremill.sttp.tapir" %%% "tapir-sttp-client" % "1.1.3"
 "io.github.cquiroz" %%% "scala-java-time" % "2.2.0" // implementations of java.time classes for Scala.JS
 ```
 

generated-doc/out/docs/asyncapi.md

@@ -3,7 +3,7 @@
 To use, add the following dependencies:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "1.1.3"
 "com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec
 ```
 

generated-doc/out/docs/openapi.md

@@ -13,7 +13,7 @@ these steps can be done separately, giving you complete control over the process
 To generate OpenAPI documentation and expose it using the Swagger UI in a single step, first add the dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.1.3"
 ```
 
 Then, you can interpret a list of endpoints using `SwaggerInterpreter`. The result will be a list of file-serving 
@@ -55,7 +55,7 @@ for details.
 Similarly as above, you'll need the following dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-redoc-bundle" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-redoc-bundle" % "1.1.3"
 ```
 
 And the server endpoints can be generated using the `sttp.tapir.redoc.bundle.RedocInterpreter` class.
@@ -65,7 +65,7 @@ And the server endpoints can be generated using the `sttp.tapir.redoc.bundle.Red
 To generate the docs in the OpenAPI yaml format, add the following dependencies:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.1.3"
 "com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec
 ```
 
@@ -126,6 +126,34 @@ import sttp.apispec.openapi.circe._
 println(Printer.spaces2.print(docs.asJson))
 ```
 
+### Support for OpenAPI 3.1.0
+
+Generating OpenAPI documentation compatible with 3.1.0 specifications is a matter of using a different encoder.
+For example, generating the OpenAPI 3.1.0 YAML string can be achieved by performing the following steps:
+
+Firstly add dependencies:
+```scala
+"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.1.3"
+"com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec
+```
+
+and generate the documentation by importing valid extension methods and explicitly specifying the "3.1.0" version in the OpenAPI model:
+```scala
+import sttp.apispec.openapi.OpenAPI
+import sttp.apispec.openapi.circe.yaml._ // for `toYaml3_1` extension method // for `toYaml3_1` extension method
+import sttp.tapir._
+import sttp.tapir.docs.openapi.OpenAPIDocsInterpreter
+
+case class Book(id: Option[Long], title: Option[String])
+
+val booksListing = endpoint.in(path[String]("bookId"))
+
+val docs: OpenAPI = OpenAPIDocsInterpreter().toOpenAPI(booksListing, "My Bookshop", "1.0")
+ .openapi("3.1.0") // "3.1.0" version explicitly specified // "3.1.0" version explicitly specified
+
+println(docs.toYaml3_1) // OpenApi 3.1.0 YAML string would be printed to the console
+```
+
 ## Exposing generated OpenAPI documentation
 
 Exposing the OpenAPI can be done using [Swagger UI](https://swagger.io/tools/swagger-ui/) or
@@ -136,12 +164,12 @@ The modules `tapir-swagger-ui` and `tapir-redoc` contain server endpoint definit
 yaml format, will expose it using the given context path. To use, add as a dependency either
 `tapir-swagger-ui`:
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui" % "1.1.3"
 ```
 
 or `tapir-redoc`:
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-redoc" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-redoc" % "1.1.3"
 ```
 
 Then, you'll need to pass the server endpoints to your server interpreter. For example, using akka-http:

generated-doc/out/endpoint/integrations.md

@@ -14,7 +14,7 @@ The `tapir-cats` module contains additional instances for some [cats](https://ty
 datatypes as well as additional syntax:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-cats" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-cats" % "1.1.3"
 ```
 
 - `import sttp.tapir.integ.cats.codec._` - brings schema, validator and codec instances
@@ -26,7 +26,7 @@ If you use [refined](https://github.com/fthomas/refined), the `tapir-refined` mo
 validators for `T Refined P` as long as a codec for `T` already exists:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-refined" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-refined" % "1.1.3"
 ```
 
 You'll need to extend the `sttp.tapir.codec.refined.TapirCodecRefined`
@@ -47,7 +47,7 @@ The `tapir-enumeratum` module provides schemas, validators and codecs for [Enume
 enumerations. To use, add the following dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-enumeratum" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-enumeratum" % "1.1.3"
 ```
 
 Then, `import sttp.tapir.codec.enumeratum._`, or extends the `sttp.tapir.codec.enumeratum.TapirCodecEnumeratum` trait.
@@ -87,7 +87,7 @@ If you use [scala-newtype](https://github.com/estatico/scala-newtype), the `tapi
 schemas for types with a `@newtype` and `@newsubtype` annotations as long as a codec and schema for its underlying value already exists:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-newtype" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-newtype" % "1.1.3"
 ```
 
 Then, `import sttp.tapir.codec.newtype._`, or extend the `sttp.tapir.codec.newtype.TapirCodecNewType` trait to bring the implicit values into scope.
@@ -98,7 +98,7 @@ If you use [monix newtypes](https://github.com/monix/newtypes), the `tapir-monix
 schemas for types which extend `NewtypeWrapped` and `NewsubtypeWrapped` annotations as long as a codec and schema for its underlying value already exists:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-monix-newtype" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-monix-newtype" % "1.1.3"
 ```
 
 Then, `import sttp.tapir.codec.monix.newtype._`, or extend the `sttp.tapir.codec.monix.newtype.TapirCodecMonixNewType` trait to bring the implicit values into scope.
@@ -110,7 +110,7 @@ For details refer to [derevo documentation](https://github.com/tofu-tf/derevo#in
 To use, add the following dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-derevo" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-derevo" % "1.1.3"
 ```
 
 Then you can derive schema for your ADT along with other typeclasses besides ADT declaration itself:

generated-doc/out/endpoint/json.md

@@ -45,7 +45,7 @@ stringJsonBody.schema(implicitly[Schema[MyBody]].as[String])
 To use [Circe](https://github.com/circe/circe), add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonCirce` trait, see [MyTapir](../mytapir.md)):
@@ -118,7 +118,7 @@ Now the above JSON object will render as
 To use [µPickle](http://www.lihaoyi.com/upickle/) add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonuPickle` trait, see [MyTapir](../mytapir.md) and add `TapirJsonuPickle` not `TapirCirceJson`):
@@ -153,7 +153,7 @@ For more examples, including making a custom encoder/decoder, see [TapirJsonuPic
 To use [Play JSON](https://github.com/playframework/play-json) add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonPlay` trait, see [MyTapir](../mytapir.md) and add `TapirJsonPlay` not `TapirCirceJson`):
@@ -169,7 +169,7 @@ Play JSON requires `Reads` and `Writes` implicit values in scope for each type y
 To use [Spray JSON](https://github.com/spray/spray-json) add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonSpray` trait, see [MyTapir](../mytapir.md) and add `TapirJsonSpray` not `TapirCirceJson`):
@@ -185,7 +185,7 @@ Spray JSON requires a `JsonFormat` implicit value in scope for each type you wan
 To use [Tethys JSON](https://github.com/tethys-json/tethys) add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonTethys` trait, see [MyTapir](../mytapir.md) and add `TapirJsonTethys` not `TapirCirceJson`):
@@ -201,7 +201,7 @@ Tethys JSON requires `JsonReader` and `JsonWriter` implicit values in scope for
 To use [Jsoniter-scala](https://github.com/plokhotnyuk/jsoniter-scala) add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "1.1.3"
 ```
 
 Next, import the package (or extend the `TapirJsonJsoniter` trait, see [MyTapir](../mytapir.md) and add `TapirJsonJsoniter` not `TapirCirceJson`):
@@ -217,7 +217,7 @@ Jsoniter Scala requires `JsonValueCodec` implicit value in scope for each type y
 To use [json4s](https://github.com/json4s/json4s) add the following dependencies to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-json4s" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-json4s" % "1.1.3"
 ```
 
 And one of the implementations:
@@ -248,7 +248,7 @@ implicit val formats: Formats = org.json4s.jackson.Serialization.formats(NoTypeH
 To use [zio-json](https://github.com/zio/zio-json), add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-json-zio" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-json-zio" % "1.1.3"
 ```
 Next, import the package (or extend the `TapirJsonZio` trait, see [MyTapir](../mytapir.md) and add `TapirJsonZio` instead of `TapirCirceJson`):
 

generated-doc/out/endpoint/xml.md

@@ -7,10 +7,11 @@ Implementation is fairly easy, and for now, one guide on how to integrate with s
 ```eval_rst
 .. note::
 
- Note, that implementing `XmlCodec[T]` would require deriving not only XML library encoders/decoders, 
- but also tapir related `Schema[T]`. These are completely separate - any customization e.g. for field
+ Note, that implementing ``XmlCodec[T]`` would require deriving not only XML library encoders/decoders, 
+ but also tapir related ``Schema[T]``. These are completely separate - any customization e.g. for field
  naming or inheritance strategies must be done separately for both derivations.
- For more details see sections on [schema derivation](schemas.md) and on supporting [custom types](customtypes.md) in general.
+ For more details see sections on `schema derivation <https://tapir.softwaremill.com/en/latest/endpoint/schemas.html>`_ 
+ and on supporting `custom types <https://tapir.softwaremill.com/en/latest/endpoint/customtypes.html>`_ in general.
 ```
 
 ## Scalaxb

generated-doc/out/generator/sbt-openapi-codegen.md

@@ -11,7 +11,7 @@
 Add the sbt plugin to the `project/plugins.sbt`:
 
 ```scala
-addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "1.1.2")
+addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "1.1.3")
 ```
 
 Enable the plugin for your project in the `build.sbt`:

generated-doc/out/grpc.md

@@ -0,0 +1,69 @@
+# gRPC
+
+Experimental feature - it's not complete and API may change
+
+tapir supports currently defining and exposing gRPC endpoints. There is also a handy tool for generating proto files
+from these endpoints' definitions.
+
+## Modules
+
+* `protobuf` - contains a Protobuf protocol model and utilities that make generating proto files handy. This module
+ should be used for generating proto files from endpoints definitions
+* `pbDirectProtobuf` - integration with `PBDirect` library. Should be used for auto codecs derivation. Currently, it's
+ necessary to add this module for generating proto files with the `protobuf` module.
+* `akkaGrpcServer` - a module that provides `AkkaGrpcServerInterpreter` implementation. It should be used to serve tapir
+ grpc endpoints.
+* `grpcExamples` - contains example use cases
+
+## Defining endpoints
+
+Every gRPC endpoint requires specifying the following values: service name, method name, input format,
+output format.
+
+In tapir, we can simply pass service and method names as strings separated with `/` to the tapir endpoint input
+definition e.g. `endpoint.in("Library" / "AddBook")` where `"Library"` is a service name and `"AddBook"` is a method
+name.
+
+Definition of an endpoint's inputs and output format is very similar to the one that we use for JSONs. We can use an
+endpoint body constructor helper `sttp.tapir.grpc.protobuf.pbdirect.grpcBody[T]` that based on the type `T` create a
+body definition that can be passed to as input or output of a given endpoint
+e.g. `endpoint.in(grpcBody[AddSimpleBook]).out(grpcBody[SimpleBook])`.
+
+Currently, the only supported protocol is protobuf. On the server side, we use
+a [PBDirect](https://github.com/47degrees/pbdirect) library for encoding and decoding messages. It derives codecs from a
+class definition which means we do not depend on the generated code from a proto file.
+
+The `grpcBody` function takes as an implicit param tapir schema definition, that is used to generate a proto file, and
+PBDirect codecs for a given type.
+Currently, we don't support passing any metadata.
+
+## Generating proto file
+
+With defined endpoints, we can move towards generating a proto file that we could use to generate clients for our API.
+
+The easiest way to do it is by using a built-in `ProtoSchemaGenerator`. We need to only choose a path for the file,
+package name, pass endpoints definitions, and finally invoke the `renderToFile` function e.g.
+
+```
+ProtoSchemaGenerator.renderToFile(
+ path = "grpc/examples/src/main/protobuf/main.proto",
+ packageName = "sttp.tapir.grpc.examples.gen",
+ endpoints = Endpoints.endpoints
+)
+```
+
+## gRPC server
+
+With the proto file, we can generate clients for our API or the server-side code
+using [ScalaPb](https://scalapb.github.io) library.
+
+It's possible to connect the generated server code to tapir endpoints definitions, but it's not convenient since depends
+on auto-generated code. We strongly recommend using the new dedicated server interpreter `AkkaGrpcServerInterpreter`.
+It's built on top of `AkkaHttpServerInterpreter` and provides support for encoding and decoding HTTP2 binary messages.
+
+[Here](https://github.com/softwaremill/tapir/grpc/examples/src/main/scala/sttp/tapir/grpc/examples/GrpcSimpleBooksExample.scala)
+you can find a simple example.
+
+It's worth mentioning that by adjusting slightly encoders/decoders it's possible to expose gRPC endpoints with 
+`AkkaHttpServerInterpreter` as simple HTTP endpoints. This approach is not recommended, because it does not support
+transmitting multiple messages in a single http request.

generated-doc/out/index.md

@@ -18,6 +18,7 @@ input and output parameters. An endpoint specification can be interpreted as:
  * [ZIO Http](server/ziohttp.md) `Http`
  * [Armeria](server/armeria.md) `HttpServiceWithRoutes` (using `Future`s, cats-effect or ZIO)
  * [aws](server/aws.md) through Lambda/SAM/Terraform
+ * [gRPC](grpc.md)
 * a client, which is a function from input parameters to output parameters.
  Currently supported:
  * [sttp](client/sttp.md)

generated-doc/out/other_interpreters.md

@@ -3,6 +3,10 @@
 At its core, tapir creates a data structure describing the HTTP endpoints. This data structure can be freely 
 interpreted also by code not included in the library. Below is a list of projects, which provide tapir interpreters.
 
+## tapir-loom
+
+The [tapir-loom](https://github.com/softwaremill/tapir-loom) project provides server interpreters which allow writing the server logic in the "direct" style (synchronous, using the `Id` effect). Depends on Java 19, which includes a preview of Project Loom (Virtual Threads for the JVM). 
+
 ## GraphQL
 
 [Caliban](https://github.com/ghostdogpr/caliban) allows you to easily turn your Tapir endpoints into a GraphQL API. More details in the [documentation](https://ghostdogpr.github.io/caliban/docs/interop.html#tapir).

generated-doc/out/quickstart.md

@@ -3,7 +3,7 @@
 To use tapir, add the following dependency to your project:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.1.3"
 ```
 
 This will import only the core classes needed to create endpoint descriptions. To generate a server or a client, you

generated-doc/out/server/akkahttp.md

@@ -4,14 +4,14 @@ To expose an endpoint as an [akka-http](https://doc.akka.io/docs/akka-http/curre
 dependency:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.1.2"
+"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.1.3"
 ```
 
 This will transitively pull some Akka modules in version 2.6. If you want to force
 your own Akka version (for example 2.5), use sbt exclusion. Mind the Scala version in artifact name:
 
 ```scala
-"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.1.2" exclude("com.typesafe.akka", "akka-stream_2.12")
+"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.1.3" exclude("com.typesafe.akka", "akka-stream_2.12")
 ```
 
 Now import the object: