diff --git a/README.md b/README.md index a81ff3c535..38a775929e 100644 --- a/README.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.2.4" ``` Then, import: diff --git a/generated-doc/out/client/http4s.md b/generated-doc/out/client/http4s.md index 39ae321b5c..ef213ac342 100644 --- a/generated-doc/out/client/http4s.md +++ b/generated-doc/out/client/http4s.md @@ -3,7 +3,7 @@ Add the dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-http4s-client" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-client" % "1.2.4" ``` To interpret an endpoint definition as an `org.http4s.Request[F]`, import: diff --git a/generated-doc/out/client/play.md b/generated-doc/out/client/play.md index 40322fbd0e..39e55314a2 100644 --- a/generated-doc/out/client/play.md +++ b/generated-doc/out/client/play.md @@ -3,7 +3,7 @@ Add the dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "1.2.4" ``` To make requests using an endpoint definition using the [play client](https://github.com/playframework/play-ws), import: diff --git a/generated-doc/out/client/sttp.md b/generated-doc/out/client/sttp.md index 7734e00aaa..bace01a4a9 100644 --- a/generated-doc/out/client/sttp.md +++ b/generated-doc/out/client/sttp.md @@ -3,7 +3,7 @@ Add the dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %%% "tapir-sttp-client" % "1.2.4" "io.github.cquiroz" %%% "scala-java-time" % "2.2.0" // implementations of java.time classes for Scala.JS ``` diff --git a/generated-doc/out/docs/asyncapi.md b/generated-doc/out/docs/asyncapi.md index 720502034c..4917beb966 100644 --- a/generated-doc/out/docs/asyncapi.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "1.2.4" "com.softwaremill.sttp.apispec" %% "asyncapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec ``` diff --git a/generated-doc/out/docs/openapi.md b/generated-doc/out/docs/openapi.md index 104ce47495..2c346f2a46 100644 --- a/generated-doc/out/docs/openapi.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-bundle" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-bundle" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.2.4" "com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec ``` @@ -133,7 +133,7 @@ For example, generating the OpenAPI 3.1.0 YAML string can be achieved by perform Firstly add dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "1.2.4" "com.softwaremill.sttp.apispec" %% "openapi-circe-yaml" % "..." // see https://github.com/softwaremill/sttp-apispec ``` @@ -164,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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui" % "1.2.4" ``` or `tapir-redoc`: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-redoc" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-redoc" % "1.2.4" ``` Then, you'll need to pass the server endpoints to your server interpreter. For example, using akka-http: diff --git a/generated-doc/out/endpoint/integrations.md b/generated-doc/out/endpoint/integrations.md index e0ec6f9528..4b035fcd82 100644 --- a/generated-doc/out/endpoint/integrations.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-cats" % "1.2.4" ``` - `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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-refined" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-enumeratum" % "1.2.4" ``` Then, `import sttp.tapir.codec.enumeratum._`, or extends the `sttp.tapir.codec.enumeratum.TapirCodecEnumeratum` trait. @@ -60,7 +60,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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-newtype" % "1.2.4" ``` Then, `import sttp.tapir.codec.newtype._`, or extend the `sttp.tapir.codec.newtype.TapirCodecNewType` trait to bring the implicit values into scope. @@ -71,7 +71,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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-monix-newtype" % "1.2.4" ``` Then, `import sttp.tapir.codec.monix.newtype._`, or extend the `sttp.tapir.codec.monix.newtype.TapirCodecMonixNewType` trait to bring the implicit values into scope. @@ -82,7 +82,7 @@ If you use [ZIO Prelude Newtypes](https://zio.github.io/zio-prelude/docs/newtype schemas for types defined using `Newtype` and `Subtype` as long as a codec and a schema for the underlying type already exists: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio-prelude" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-zio-prelude" % "1.2.4" ``` Then, mix in `sttp.tapir.codec.zio.prelude.newtype.TapirNewtypeSupport` into your newtype to bring the implicit values into scope: @@ -121,7 +121,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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-derevo" % "1.2.4" ``` Then you can derive schema for your ADT along with other typeclasses besides ADT declaration itself: diff --git a/generated-doc/out/endpoint/json.md b/generated-doc/out/endpoint/json.md index bcd2ec5cb1..7820f44753 100644 --- a/generated-doc/out/endpoint/json.md +++ b/generated-doc/out/endpoint/json.md @@ -3,7 +3,7 @@ Json values are supported through codecs, which encode/decode values to json strings. Most often, you'll be using a third-party library to perform the actual json parsing/printing. See below for the list of supported libraries. -All the integrations, when imported into scope, define a `jsonBody[T]` method. +All the integrations, when imported into scope, define `jsonBody[T]` and `jsonQuery[T]` methods. Instead of providing the json codec as an implicit value, this method depends on library-specific implicits being in scope, and basing on these values creates a json codec. The derivation also requires @@ -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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-json4s" % "1.2.4" ``` 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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-json-zio" % "1.2.4" ``` Next, import the package (or extend the `TapirJsonZio` trait, see [MyTapir](../mytapir.md) and add `TapirJsonZio` instead of `TapirCirceJson`): @@ -258,6 +258,21 @@ import sttp.tapir.json.zio._ Zio JSON requires `JsonEncoder` and `JsonDecoder` implicit values in scope for each type you want to serialize. +## JSON query parameters + +You can specify query parameters in JSON format by using the `jsonQuery` method. For example, using Circe: + +```scala +import sttp.tapir._ +import sttp.tapir.json.circe._ +import sttp.tapir.generic.auto._ +import io.circe.generic.auto._ + +case class Book(author: String, title: String, year: Int) + +val bookQuery: EndpointInput.Query[Book] = jsonQuery[Book]("book") +``` + ## Other JSON libraries To add support for additional JSON libraries, see the @@ -271,8 +286,8 @@ of [schema derivation](schemas.md) will have to match the configuration of your have different defaults when it comes to a discrimination strategy, so in order to have the schemas (and hence the documentation) in sync with how the values are serialised, you will have to configure schema derivation as well. -Schemas are referenced at the point of `jsonBody` usage, so any configuration must be available in the implicit scope -when this method is called. +Schemas are referenced at the point of `jsonBody` and `jsonQuery` usage, so any configuration must be available in the implicit scope +when these methods are called. ## Next diff --git a/generated-doc/out/endpoint/security.md b/generated-doc/out/endpoint/security.md index 7ddb59cb37..caad4d5539 100644 --- a/generated-doc/out/endpoint/security.md +++ b/generated-doc/out/endpoint/security.md @@ -33,10 +33,7 @@ base64-encoded username/password combination, use: `basic[UsernamePassword]`. as a string, use: `bearer[String]`. * `auth.oauth2.authorizationCode(authorizationUrl, tokenUrl, scopes, 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](../openapi.md)) - -Optional and multiple authentication inputs have some additional rules as to how hey map to documentation, see the -[OpenAPI](../docs/openapi.md) page for details. +the `oauth2-redirect.html`, see [Generating OpenAPI documentation](..docs/openapi.md)) ## Authentication challenges @@ -47,6 +44,11 @@ status codes when authentication is missing, the decode failure handler can [be For example, if you define `endpoint.get.securityIn("path").securityIn(auth.basic[UsernamePassword]())` then the browser will show you a password prompt. +## Grouping authentication inputs in docs + +Optional and multiple authentication inputs have some additional rules as to how hey map to documentation, see the +["Authentication inputs and security requirements"](../docs/openapi.md) section in the OpenAPI docs for details. + ## Next Read on about [streaming support](streaming.md). diff --git a/generated-doc/out/generator/sbt-openapi-codegen.md b/generated-doc/out/generator/sbt-openapi-codegen.md index 80cadbcc15..c37aa54494 100644 --- a/generated-doc/out/generator/sbt-openapi-codegen.md +++ b/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.2.3") +addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "1.2.4") ``` Enable the plugin for your project in the `build.sbt`: diff --git a/generated-doc/out/index.md b/generated-doc/out/index.md index 4f24382569..5e9d184f8f 100644 --- a/generated-doc/out/index.md +++ b/generated-doc/out/index.md @@ -11,7 +11,7 @@ input and output parameters. An endpoint specification can be interpreted as: Currently supported: * [Akka HTTP](server/akkahttp.md) `Route`s/`Directive`s * [Http4s](server/http4s.md) `HttpRoutes[F]` (using cats-effect or [ZIO](server/zio-http4s.md)) - * [Netty](server/netty.md) (using `Future`s or cats-effect) + * [Netty](server/netty.md) (using `Future`s, cats-effect or ZIO) * [Finatra](server/finatra.md) `http.Controller` * [Play](server/play.md) `Route` * [Vert.X](server/vertx.md) `Router => Route` (using `Future`s, cats-effect or ZIO) diff --git a/generated-doc/out/quickstart.md b/generated-doc/out/quickstart.md index 6e09752233..9585bd4695 100644 --- a/generated-doc/out/quickstart.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "1.2.4" ``` This will import only the core classes needed to create endpoint descriptions. To generate a server or a client, you diff --git a/generated-doc/out/server/akkahttp.md b/generated-doc/out/server/akkahttp.md index 091d547d4a..4a965d133b 100644 --- a/generated-doc/out/server/akkahttp.md +++ b/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.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.2.4" ``` 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.2.3" exclude("com.typesafe.akka", "akka-stream_2.12") +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "1.2.4" exclude("com.typesafe.akka", "akka-stream_2.12") ``` Now import the object: diff --git a/generated-doc/out/server/armeria.md b/generated-doc/out/server/armeria.md index 60474b93d7..19eb092bf7 100644 --- a/generated-doc/out/server/armeria.md +++ b/generated-doc/out/server/armeria.md @@ -8,7 +8,7 @@ Armeria interpreter can be used with different effect systems (cats-effect, ZIO) Add the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-armeria-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-armeria-server" % "1.2.4" ``` and import the object: @@ -75,7 +75,7 @@ Note that Armeria automatically injects an `ExecutionContext` on top of Armeria' Add the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-cats" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-cats" % "1.2.4" ``` to use this interpreter with Cats Effect typeclasses. @@ -155,9 +155,9 @@ Add the following dependency ```scala // for zio 2: -"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-zio" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-zio" % "1.2.4" // for zio 1: -"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-zio1" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-armeria-server-zio1" % "1.2.4" ``` to use this interpreter with ZIO. diff --git a/generated-doc/out/server/aws.md b/generated-doc/out/server/aws.md index bdbd6af3a5..3882100054 100644 --- a/generated-doc/out/server/aws.md +++ b/generated-doc/out/server/aws.md @@ -13,7 +13,7 @@ To implement the Lambda function, a server interpreter is available, which takes Currently, only an interpreter integrating with cats-effect is available (`AwsCatsEffectServerInterpreter`). To use, add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-aws-lambda" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-aws-lambda" % "1.2.4" ``` To configure API Gateway and the Lambda function, you can use: @@ -24,8 +24,8 @@ To configure API Gateway and the Lambda function, you can use: Add one of the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-aws-sam" % "1.2.3" -"com.softwaremill.sttp.tapir" %% "tapir-aws-terraform" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-aws-sam" % "1.2.4" +"com.softwaremill.sttp.tapir" %% "tapir-aws-terraform" % "1.2.4" ``` ## Examples diff --git a/generated-doc/out/server/errors.md b/generated-doc/out/server/errors.md index 9bfa75891f..6a0aa220d0 100644 --- a/generated-doc/out/server/errors.md +++ b/generated-doc/out/server/errors.md @@ -112,9 +112,41 @@ an error or return a "no match", create error messages and create the response. swapped, e.g. to return responses in a different format (other than plain text), or customise the error messages. The default decode failure handler also has the option to return a `400 Bad Request`, instead of a no-match (ultimately -leading to a `404 Not Found`), when the "shape" of the path matches (that is, the number of segments in the request -and endpoint's paths are the same), but when decoding some part of the path ends in an error. See the -`badRequestOnPathErrorIfPathShapeMatches` in `ServerDefaults`. +leading to a `404 Not Found`), when the "shape" of the path matches (that is, the constant parts and number of segments +in the request and endpoint's paths are the same), but when decoding some part of the path ends in an error. See the +scaladoc for `DefaultDecodeFailureHandler.default` and parameters of `DefaultDecodeFailureHandler.response`. For example: + +```scala +import sttp.tapir._ +import sttp.tapir.server.akkahttp.AkkaHttpServerOptions +import sttp.tapir.server.interceptor.decodefailure.DefaultDecodeFailureHandler +import scala.concurrent.ExecutionContext.Implicits.global + +val myDecodeFailureHandler = DefaultDecodeFailureHandler.default.copy( + respond = DefaultDecodeFailureHandler.respond( + _, + badRequestOnPathErrorIfPathShapeMatches = true, + badRequestOnPathInvalidIfPathShapeMatches = true + ) +) + +val myServerOptions: AkkaHttpServerOptions = AkkaHttpServerOptions + .customiseInterceptors + .decodeFailureHandler(myDecodeFailureHandler) + .options +``` + +Moreover, when using the `DefaultDecodeFailureHandler`, decode failure handling can be overriden on a per-input/output +basis, by setting an attribute. For example: + +```scala +import sttp.tapir._ +// bringing into scope the onDecodeFailureBadRequest extension method +import sttp.tapir.server.interceptor.decodefailure.DefaultDecodeFailureHandler.OnDecodeFailure._ + +// by default, when the customer_id is not an int, the next endpoint would be tried; here, we always return a bad request +endpoint.in("customer" / path[Int]("customer_id").onDecodeFailureBadRequest) +``` ## Customising how error messages are rendered diff --git a/generated-doc/out/server/finatra.md b/generated-doc/out/server/finatra.md index 05f9896bdd..4a441eaddf 100644 --- a/generated-doc/out/server/finatra.md +++ b/generated-doc/out/server/finatra.md @@ -4,7 +4,7 @@ To expose an endpoint as an [finatra](https://twitter.github.io/finatra/) server dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-finatra-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server" % "1.2.4" ``` and import the object: @@ -17,7 +17,7 @@ This interpreter supports the twitter `Future`. Or, if you would like to use cats-effect project, you can add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-finatra-server-cats" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server-cats" % "1.2.4" ``` and import the object: diff --git a/generated-doc/out/server/http4s.md b/generated-doc/out/server/http4s.md index 22d491ff34..15a8a03e39 100644 --- a/generated-doc/out/server/http4s.md +++ b/generated-doc/out/server/http4s.md @@ -4,7 +4,7 @@ To expose an endpoint as an [http4s](https://http4s.org) server, first add the f dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % "1.2.4" ``` and import the object: diff --git a/generated-doc/out/server/netty.md b/generated-doc/out/server/netty.md index 72f256a441..a4f7144acb 100644 --- a/generated-doc/out/server/netty.md +++ b/generated-doc/out/server/netty.md @@ -4,16 +4,23 @@ To expose an endpoint using a [Netty](https://netty.io)-based server, first add ```scala // if you are using Future or just exploring -"com.softwaremill.sttp.tapir" %% "tapir-netty-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-netty-server" % "1.2.4" // if you are using cats-effect: -"com.softwaremill.sttp.tapir" %% "tapir-netty-server-cats" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-netty-server-cats" % "1.2.4" + +// if you are using zio: +"com.softwaremill.sttp.tapir" %% "tapir-netty-server-zio" % "1.2.4" + +// if you are using zio1: +"com.softwaremill.sttp.tapir" %% "tapir-netty-server-zio1" % "1.2.4" ``` Then, use: * `NettyFutureServer().addEndpoints` to expose `Future`-based server endpoints. * `NettyCatsServer().addEndpoints` to expose `F`-based server endpoints, where `F` is any cats-effect supported effect. +* `NettyZioServer().addEndpoints` to expose `ZIO`-based server endpoints, where `R` represents ZIO requirements supported effect. These methods require a single, or a list of `ServerEndpoint`s, which can be created by adding [server logic](logic.md) to an endpoint. diff --git a/generated-doc/out/server/observability.md b/generated-doc/out/server/observability.md index 7ac782dbeb..cf441cc38f 100644 --- a/generated-doc/out/server/observability.md +++ b/generated-doc/out/server/observability.md @@ -49,7 +49,7 @@ val labels = MetricLabels( Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-prometheus-metrics" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-prometheus-metrics" % "1.2.4" ``` `PrometheusMetrics` encapsulates `CollectorReqistry` and `Metric` instances. It provides several ready to use metrics as @@ -130,7 +130,7 @@ val prometheusMetrics = PrometheusMetrics[Future]("tapir", CollectorRegistry.def Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-opentelemetry-metrics" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-opentelemetry-metrics" % "1.2.4" ``` OpenTelemetry metrics are vendor-agnostic and can be exported using one @@ -157,7 +157,7 @@ val metricsInterceptor = metrics.metricsInterceptor() // add to your server opti Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-datadog-metrics" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-datadog-metrics" % "1.2.4" ``` Datadog metrics are sent as Datadog custom metrics through @@ -224,7 +224,7 @@ val datadogMetrics = DatadogMetrics.default[Future](statsdClient) Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio-metrics" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-zio-metrics" % "1.2.4" ``` Metrics have been integrated into ZIO core in ZIO2. diff --git a/generated-doc/out/server/play.md b/generated-doc/out/server/play.md index 5efb224d7e..adf16f7af2 100644 --- a/generated-doc/out/server/play.md +++ b/generated-doc/out/server/play.md @@ -3,7 +3,7 @@ To expose endpoint as a [play-server](https://www.playframework.com/) first add the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-play-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-play-server" % "1.2.4" ``` and (if you don't already depend on Play) diff --git a/generated-doc/out/server/vertx.md b/generated-doc/out/server/vertx.md index a5cbfe94d4..5c50e1727a 100644 --- a/generated-doc/out/server/vertx.md +++ b/generated-doc/out/server/vertx.md @@ -8,7 +8,7 @@ Vert.x interpreter can be used with different effect systems (cats-effect, ZIO) Add the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "1.2.4" ``` to use this interpreter with `Future`. @@ -63,7 +63,7 @@ It's also possible to define an endpoint together with the server logic in a sin Add the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-cats" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-cats" % "1.2.4" ``` to use this interpreter with Cats Effect typeclasses. @@ -146,9 +146,9 @@ Add the following dependency ```scala // for zio2: -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-zio" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-zio" % "1.2.4" // for zio1: -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-zio1" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server-zio1" % "1.2.4" ``` to use this interpreter with ZIO. diff --git a/generated-doc/out/server/zio-http4s.md b/generated-doc/out/server/zio-http4s.md index f86dd4d81a..64ed6d6363 100644 --- a/generated-doc/out/server/zio-http4s.md +++ b/generated-doc/out/server/zio-http4s.md @@ -9,16 +9,16 @@ The `*-zio` modules depend on ZIO 2.x. For ZIO 1.x support, use modules with the You'll need the following dependency for the `ZServerEndpoint` type alias and helper classes: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-zio" % "1.2.4" ``` or just add the zio-http4s integration which already depends on `tapir-zio`: ```scala // for zio 2: -"com.softwaremill.sttp.tapir" %% "tapir-http4s-server-zio" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-server-zio" % "1.2.4" // for zio 1: -"com.softwaremill.sttp.tapir" %% "tapir-http4s-server-zio1" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-server-zio1" % "1.2.4" ``` Next, instead of the usual `import sttp.tapir._`, you should import (or extend the `ZTapir` trait, see [MyTapir](../mytapir.md)): diff --git a/generated-doc/out/server/ziohttp.md b/generated-doc/out/server/ziohttp.md index 7cf9dc945c..333002d7ca 100644 --- a/generated-doc/out/server/ziohttp.md +++ b/generated-doc/out/server/ziohttp.md @@ -9,13 +9,13 @@ The `*-zio` modules depend on ZIO 2.x. For ZIO 1.x support, use modules with the You'll need the following dependency for the `ZServerEndpoint` type alias and helper classes: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-zio" % "1.2.4" ``` or just add the zio-http integration which already depends on `tapir-zio`: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio-http-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-zio-http-server" % "1.2.4" ``` Next, instead of the usual `import sttp.tapir._`, you should import (or extend the `ZTapir` trait, see [MyTapir](../mytapir.md)): diff --git a/generated-doc/out/testing.md b/generated-doc/out/testing.md index 3214188ef8..2625081597 100644 --- a/generated-doc/out/testing.md +++ b/generated-doc/out/testing.md @@ -23,7 +23,7 @@ Tapir builds upon the `SttpBackendStub` to enable stubbing using `Endpoint`s or dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "1.2.4" ``` Let's assume you are using the [akka http](server/akkahttp.md) interpreter. Given the following server endpoint: @@ -140,7 +140,7 @@ requests matching an endpoint, you can use the tapir `SttpBackendStub` extension Similarly as when testing server interpreters, add the dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "1.2.4" ``` And the following imports: @@ -195,7 +195,7 @@ with [mock-server](https://www.mock-server.com/) Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-sttp-mock-server" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-mock-server" % "1.2.4" ``` Imports: @@ -266,7 +266,7 @@ result == out To use, add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-testing" % "1.2.3" +"com.softwaremill.sttp.tapir" %% "tapir-testing" % "1.2.4" ``` ### Shadowed endpoints