diff --git a/README.md b/README.md index e141768f55..40a6feed0d 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ tapir documentation is available at [tapir.softwaremill.com](http://tapir.softwa Add the following dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-core" % "0.17.0-M11" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "0.17.0" ``` You'll need partial unification enabled in the compiler (alternatively, you'll need to manually provide type arguments in some cases): diff --git a/generated-doc/out/client/play.md b/generated-doc/out/client/play.md index fe752a17d9..ef9995925d 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "0.17.0" ``` 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 751fb48b2a..5e6022bf52 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "0.17.0" ``` To make requests using an endpoint definition using the [sttp client](https://github.com/softwaremill/sttp), import: diff --git a/generated-doc/out/docs/asyncapi.md b/generated-doc/out/docs/asyncapi.md index 788e608aaf..64f37955a6 100644 --- a/generated-doc/out/docs/asyncapi.md +++ b/generated-doc/out/docs/asyncapi.md @@ -3,8 +3,8 @@ To use, add the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-circe-yaml" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-circe-yaml" % "0.17.0" ``` Tapir contains a case class-based model of the asyncapi data structures in the `asyncapi/asyncapi-model` subproject (the diff --git a/generated-doc/out/docs/openapi.md b/generated-doc/out/docs/openapi.md index 8a58955e1d..e10acd7b43 100644 --- a/generated-doc/out/docs/openapi.md +++ b/generated-doc/out/docs/openapi.md @@ -3,8 +3,8 @@ To use, add the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-openapi-circe-yaml" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-circe-yaml" % "0.17.0" ``` Tapir contains a case class-based model of the openapi data structures in the `openapi/openapi-model` subproject (the @@ -70,26 +70,26 @@ akka-http/http4s routes for exposing documentation using [Swagger UI](https://sw ```scala // Akka HTTP -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-akka-http" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-akka-http" % "0.17.0" // Finatra -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-finatra" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-finatra" % "0.17.0" // HTTP4S -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-http4s" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-http4s" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-http4s" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-http4s" % "0.17.0" // Play -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-play" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-play" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-play" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-play" % "0.17.0" ``` Note: `tapir-swagger-ui-akka-http` transitively pulls 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-swagger-ui-akka-http" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" exclude("com.typesafe.akka", "akka-stream_2.12") +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.17.0" exclude("com.typesafe.akka", "akka-stream_2.12") ``` Usage example for akka-http: diff --git a/generated-doc/out/endpoint/integrations.md b/generated-doc/out/endpoint/integrations.md index 96fd71a34c..89262e0e4e 100644 --- a/generated-doc/out/endpoint/integrations.md +++ b/generated-doc/out/endpoint/integrations.md @@ -6,7 +6,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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-cats" % "0.17.0" ``` - `import sttp.tapir.integ.cats.codec._` - brings schema, validator and codec instances @@ -19,7 +19,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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-refined" % "0.17.0" ``` You'll need to extend the `sttp.tapir.codec.refined.TapirCodecRefined` @@ -40,7 +40,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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-enumeratum" % "0.17.0" ``` Then, `import sttp.tapir.codec.enumeratum`, or extends the `sttp.tapir.codec.enumeratum.TapirCodecEnumeratum` trait. diff --git a/generated-doc/out/endpoint/ios.md b/generated-doc/out/endpoint/ios.md index 66015ae25e..136ce5f6de 100644 --- a/generated-doc/out/endpoint/ios.md +++ b/generated-doc/out/endpoint/ios.md @@ -130,9 +130,9 @@ val paging: EndpointInput[Paging] = Mapping methods can also be called on an endpoint (which is useful if inputs/outputs are accumulated, for example). The `Endpoint.mapIn`, `Endpoint.mapInTo` etc. have the same signatures are the ones above. -## Describing input values using annotations +## Describing input/output values using annotations -Inputs can also be built for case classes using annotations. For example, for the case class `User` +Inputs and outputs can also be built for case classes using annotations. For example, for the case class `User` ```scala import sttp.tapir.annotations._ @@ -151,17 +151,23 @@ val userInput: EndpointInput[User] = query[String]("user").and(cookie[Long]("sessionId")).mapTo(User) ``` -Following annotations are available in package `sttp.tapir.annotations` for describing input values: -* `@query` captures a query parameter with the same name as name of annotated field in a case class. This annotation -can also be used with optional parameter `@query("paramName")` in order to capture a query parameter with name `"paramName"` -if a name of query parameter is different from name of annotated field in a case class -* `@params` captures all query parameters. Can only be applied to fields represented as `QueryParams` -* `@header` captures a header with the same name as name of annotated field in a case class. The same as annotation -`@query` it has optional parameter to specify alternative name for header +Following annotations are available in package `sttp.tapir.annotations` for describing both input and output values: +* `@header` captures a header with the same name as name of annotated field in a case class. This annotation +can also be used with optional parameter `@header("headerName")` in order to capture a header with name `"headerName"` +if a name of header is different from name of annotated field in a case class * `@headers` captures all headers. Can only be applied to fields represented as `List[Header]` -* `@cookie` captures a cookie with the same name as name of annotated field in a case class. The same as annotation -`@query` it has optional parameter to specify alternative name for cookie * `@cookies` captures all cookies. Can only be applied to fields represented as `List[Cookie]` +* `@jsonbody` captures JSON body of request or response. Can only be applied to field if there is implicit JSON `Codec` +instance from `String` to target type +* `@xmlbody` captures XML body of request or response. Also requires implicit XML `Codec` instance from `String` to +target type + +Following annotations are only available for describing input values: +* `@query` captures a query parameter with the same name as name of annotated field in a case class. The same as +annotation `@header` it has optional parameter to specify alternative name for query parameter +* `@params` captures all query parameters. Can only be applied to fields represented as `QueryParams` +* `@cookie` captures a cookie with the same name as name of annotated field in a case class. The same as annotation +`@header` it has optional parameter to specify alternative name for cookie * `@path` captures a path segment. Can only be applied to field of a case class if this case class is annotated by annotation `@endpointInput`. For example, ```scala @@ -179,13 +185,16 @@ case class Book( ``` Annotation `@endpointInput` specifies endpoint path. In order to capture one segment of this path it must be surrounded in curly braces -* `@jsonbody` captures JSON body of request. Can only be applied to field if there is implicit JSON `Codec` instance -from `String` to target type -* `@xmlbody` captures XML body of request. Also requires implicit XML `Codec` instance from `String` to target type * `@apikey` wraps any other input and designates it as an API key. Can only be used with another annotations * `@basic` extracts data from the `Authorization` header. Can only be applied for field represented as `UsernamePassword` * `@bearer` extracts data from the `Authorization` header removing the `Bearer` prefix. +Following annotations are only available for describing output values: +* `@setCookie` sends value in header `Set-Cookie`. The same as annotation `@header` it has optional parameter to specify +alternative name for cookie. Can only be applied for field represented as `CookieValueWithMeta` +* `@setCookies` sends several `Set-Cookie` headers. Can only be applied for field represented as `List[Cookie]` +* `@statusCode` sets status code for response. Can only be applied for field represented as `StatusCode` + ## Path matching By default (as with all other types of inputs), if no path input/path segments are defined, any path will match. diff --git a/generated-doc/out/endpoint/json.md b/generated-doc/out/endpoint/json.md index 1f08265434..d780bfa97e 100644 --- a/generated-doc/out/endpoint/json.md +++ b/generated-doc/out/endpoint/json.md @@ -19,7 +19,7 @@ the json codec that is in scope. To use Circe add the following dependency to your project: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonCirce` trait, see [MyTapir](../mytapir.md)): @@ -93,7 +93,7 @@ Now the above JSON object will render as To use µPickle add the following dependency to your project: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonuPickle` trait, see [MyTapir](../mytapir.md) and add `TapirJsonuPickle` not `TapirCirceJson`): @@ -128,7 +128,7 @@ For more examples, including making a custom encoder/decoder, see [TapirJsonuPic To use Play JSON add the following dependency to your project: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonPlay` trait, see [MyTapir](../mytapir.md) and add `TapirJsonPlay` not `TapirCirceJson`): @@ -144,7 +144,7 @@ Play JSON requires `Reads` and `Writes` implicit values in scope for each type y To use Spray JSON add the following dependency to your project: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonSpray` trait, see [MyTapir](../mytapir.md) and add `TapirJsonSpray` not `TapirCirceJson`): @@ -160,7 +160,7 @@ Spray JSON requires a `JsonFormat` implicit value in scope for each type you wan To use Tethys JSON add the following dependency to your project: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonTethys` trait, see [MyTapir](../mytapir.md) and add `TapirJsonTethys` not `TapirCirceJson`): @@ -176,7 +176,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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "0.17.0" ``` Next, import the package (or extend the `TapirJsonJsoniter` trait, see [MyTapir](../mytapir.md) and add `TapirJsonJsoniter` not `TapirCirceJson`): diff --git a/generated-doc/out/endpoint/zio.md b/generated-doc/out/endpoint/zio.md index cfbc406ab0..bf95f5e522 100644 --- a/generated-doc/out/endpoint/zio.md +++ b/generated-doc/out/endpoint/zio.md @@ -7,8 +7,8 @@ exposing the endpoints using the [http4s](https://http4s.org) server. You'll need the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-zio" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" -"com.softwaremill.sttp.tapir" %% "tapir-zio-http4s-server" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-zio" % "0.17.0" +"com.softwaremill.sttp.tapir" %% "tapir-zio-http4s-server" % "0.17.0" ``` Next, instead of the usual `import sttp.tapir._`, you should import: diff --git a/generated-doc/out/generator/sbt-openapi-codegen.md b/generated-doc/out/generator/sbt-openapi-codegen.md index d71085ffe9..a4fdd2e819 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT") +addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "0.17.0") ``` Enable the plugin for your project in the `build.sbt`: diff --git a/generated-doc/out/quickstart.md b/generated-doc/out/quickstart.md index 4e9ed17926..0a5dafda24 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "0.17.0" ``` 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 0bdf9b7c4e..a54dbb3cc8 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "0.17.0" ``` 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" exclude("com.typesafe.akka", "akka-stream_2.12") +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "0.17.0" exclude("com.typesafe.akka", "akka-stream_2.12") ``` Now import the package: diff --git a/generated-doc/out/server/finatra.md b/generated-doc/out/server/finatra.md index 95df55940d..2ab3c4d81e 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server" % "0.17.0" ``` and import the package: @@ -16,7 +16,7 @@ import sttp.tapir.server.finatra._ 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server-cats" % "0.17.0" ``` and import the packate: diff --git a/generated-doc/out/server/http4s.md b/generated-doc/out/server/http4s.md index 60446a8339..7aee4d5bf7 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % "0.17.0" ``` and import the package: diff --git a/generated-doc/out/server/play.md b/generated-doc/out/server/play.md index a5c78cedc3..c4e69b2ff2 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" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-play-server" % "0.17.0" ``` 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 ff8ce51336..490afe82ce 100644 --- a/generated-doc/out/server/vertx.md +++ b/generated-doc/out/server/vertx.md @@ -4,7 +4,7 @@ Endpoints can be mounted as Vert.x `Route`s on top of a Vert.x `Router`. Use the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.0" ``` Then import the package: diff --git a/generated-doc/out/testing.md b/generated-doc/out/testing.md index 526aedf0d2..2568c968cf 100644 --- a/generated-doc/out/testing.md +++ b/generated-doc/out/testing.md @@ -12,7 +12,7 @@ details on how the stub works). Add the dependency: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "0.17.0-M11+25-8d0263ff+20201216-0826-SNAPSHOT" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "0.17.0" ``` And the following imports: