From d4a7b46de617d8b909791d83eb135d22884e2389 Mon Sep 17 00:00:00 2001 From: adamw Date: Thu, 11 Feb 2021 08:54:22 +0100 Subject: [PATCH] Release 0.17.10 --- README.md | 2 +- generated-doc/out/client/play.md | 2 +- generated-doc/out/client/sttp.md | 2 +- generated-doc/out/docs/asyncapi.md | 4 +-- generated-doc/out/docs/openapi.md | 35 ++++++++++++------- generated-doc/out/endpoint/customtypes.md | 1 + generated-doc/out/endpoint/integrations.md | 12 +++---- generated-doc/out/endpoint/json.md | 14 ++++---- generated-doc/out/endpoint/validation.md | 9 ++--- generated-doc/out/endpoint/zio.md | 4 +-- .../out/generator/sbt-openapi-codegen.md | 2 +- generated-doc/out/quickstart.md | 2 +- generated-doc/out/server/akkahttp.md | 4 +-- generated-doc/out/server/finatra.md | 4 +-- generated-doc/out/server/http4s.md | 2 +- generated-doc/out/server/play.md | 2 +- generated-doc/out/server/vertx.md | 6 ++-- generated-doc/out/testing.md | 2 +- 18 files changed, 60 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 498e3bcd7e..e0217bc99b 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,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.9" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "0.17.10" ``` 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 09f0320403..7df627956f 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-play-client" % "0.17.10" ``` 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 4335790fbf..d5e26ae956 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-client" % "0.17.10" ``` 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 36ddb019f2..d8191ef72e 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.9" -"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-circe-yaml" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-docs" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-asyncapi-circe-yaml" % "0.17.10" ``` 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 52b042e578..997208af74 100644 --- a/generated-doc/out/docs/openapi.md +++ b/generated-doc/out/docs/openapi.md @@ -1,10 +1,11 @@ + # Generating OpenAPI documentation To use, add the following dependencies: ```scala -"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "0.17.9" -"com.softwaremill.sttp.tapir" %% "tapir-openapi-circe-yaml" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-docs" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-openapi-circe-yaml" % "0.17.10" ``` Tapir contains a case class-based model of the openapi data structures in the `openapi/openapi-model` subproject (the @@ -46,7 +47,7 @@ Multiple endpoints can be converted to an `OpenAPI` instance by calling the meth OpenAPIDocsInterpreter.toOpenAPI(List(addBook, booksListing, booksListingByGenre), "My Bookshop", "1.0") ``` -The openapi case classes can then be serialised, either to JSON or YAML using [Circe](https://circe.github.io/circe/): +The openapi case classes can then be serialised to YAML using [Circe](https://circe.github.io/circe/): ```scala import sttp.tapir.openapi.circe.yaml._ @@ -54,6 +55,16 @@ import sttp.tapir.openapi.circe.yaml._ println(docs.toYaml) ``` +Or to JSON: + +```scala +import io.circe.Printer +import io.circe.syntax._ +import sttp.tapir.openapi.circe._ + +println(Printer.spaces2.print(docs.asJson)) +``` + ## Options Options can be customised by providing an implicit instance of `OpenAPIDocsOptions`, when calling `.toOpenAPI`. @@ -70,29 +81,29 @@ 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.9" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-akka-http" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-akka-http" % "0.17.10" // Finatra -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-finatra" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-finatra" % "0.17.10" // HTTP4S -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-http4s" % "0.17.9" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-http4s" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-http4s" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-http4s" % "0.17.10" // Play -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-play" % "0.17.9" -"com.softwaremill.sttp.tapir" %% "tapir-redoc-play" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-play" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-redoc-play" % "0.17.10" // Vert.x -"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-vertx" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-vertx" % "0.17.10" ``` 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.9" exclude("com.typesafe.akka", "akka-stream_2.12") +"com.softwaremill.sttp.tapir" %% "tapir-swagger-ui-akka-http" % "0.17.10" exclude("com.typesafe.akka", "akka-stream_2.12") ``` Usage example for akka-http: diff --git a/generated-doc/out/endpoint/customtypes.md b/generated-doc/out/endpoint/customtypes.md index caec394d22..e48f4a9124 100644 --- a/generated-doc/out/endpoint/customtypes.md +++ b/generated-doc/out/endpoint/customtypes.md @@ -217,6 +217,7 @@ field of a case class. One way the automatic derivation can be customised is usi * `@encodedName` sets name for case class's field which is used in the encoded form (and also in documentation) * `@description` sets description for the whole case class or its field * `@default` sets default value for a case class field +* `@encodedExample` sets example value for a case class field which is used in the documentation in the encoded form * `@format` sets the format for a case class field * `@deprecated` marks a case class's field as deprecated diff --git a/generated-doc/out/endpoint/integrations.md b/generated-doc/out/endpoint/integrations.md index 3d68839a0d..9252ba41ff 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-cats" % "0.17.10" ``` - `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.9" +"com.softwaremill.sttp.tapir" %% "tapir-refined" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-enumeratum" % "0.17.10" ``` Then, `import sttp.tapir.codec.enumeratum`, or extends the `sttp.tapir.codec.enumeratum.TapirCodecEnumeratum` trait. @@ -55,8 +55,6 @@ The example code below will generate [enums](https://swagger.io/docs/specificati ```scala import sttp.tapir._ -import sttp.tapir.codec.enumeratum._ -import enumeratum._ trait EnumHelper { e: Enumeration => import io.circe._ @@ -64,8 +62,8 @@ trait EnumHelper { e: Enumeration => implicit val enumDecoder: Decoder[e.Value] = Decoder.decodeEnumeration(e) implicit val enumEncoder: Encoder[e.Value] = Encoder.encodeEnumeration(e) - implicit val schemaForEnum: Schema[e.Value] = Schema.string - implicit def validatorForEnum: Validator[e.Value] = Validator.`enum`(e.values.toList, v => Option(v)) + // needs to be a def or lazy val so that the enumeration values are available! + implicit def schemaForEnum: Schema[e.Value] = Schema.string.validate(Validator.enum(e.values.toList, v => Option(v))) } object Color extends Enumeration with EnumHelper { type Color = Value diff --git a/generated-doc/out/endpoint/json.md b/generated-doc/out/endpoint/json.md index da470e3a68..6e58613235 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-json-circe" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-json-upickle" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-json-play" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-json-spray" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-json-tethys" % "0.17.10" ``` 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-jsoniter-scala" % "0.17.10" ``` Next, import the package (or extend the `TapirJsonJsoniter` trait, see [MyTapir](../mytapir.md) and add `TapirJsonJsoniter` not `TapirCirceJson`): @@ -193,7 +193,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-json4s" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-json4s" % "0.17.10" ``` And one of the implementations: diff --git a/generated-doc/out/endpoint/validation.md b/generated-doc/out/endpoint/validation.md index 218428bef1..2c1445f433 100644 --- a/generated-doc/out/endpoint/validation.md +++ b/generated-doc/out/endpoint/validation.md @@ -6,8 +6,9 @@ dedicated error output (the `E` in `Endpoint[I, E, O, S]`) to report errors. ## Single type validation -Validation rules are part of the [codec](codecs.md) for a given type. They can be specified when creating the codec -(using the `Codec.validate()` method): +Validation rules are part of the [`Schema`](codecs.md#schemas) for a given type, and can be added either directly +to the schema, or via the `Codec` or `EndpointInput`/`EndpointOutput`. For example, when defining a codec for a type, +we have the `.validate()` method: ```scala import sttp.tapir._ @@ -35,9 +36,9 @@ Validation rules added using the built-in validators are translated to [OpenAPI] ## Validation rules and automatic codec derivation -Validator are parts of schemas, validators are looked up as part of the with implicit `Schema[T]` values. +As validators are parts of schemas, they are looked up as part of the with implicit `Schema[T]` values. -While they can be manually defined, Tapir provides tools to derive automatically schemas for custom types +While they can be manually defined, tapir provides tools to derive automatically schemas for custom types (traits and case classes). ## Custom type validation diff --git a/generated-doc/out/endpoint/zio.md b/generated-doc/out/endpoint/zio.md index 89fc9a9b96..2172ea475b 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.9" -"com.softwaremill.sttp.tapir" %% "tapir-zio-http4s-server" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-zio" % "0.17.10" +"com.softwaremill.sttp.tapir" %% "tapir-zio-http4s-server" % "0.17.10" ``` 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 3dac73b331..f0b8091f60 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.9") +addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "0.17.10") ``` 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 4b6924e3cb..bf30c5b72b 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-core" % "0.17.10" ``` 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 2821d7ebad..11af67ade1 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "0.17.10" ``` 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.9" exclude("com.typesafe.akka", "akka-stream_2.12") +"com.softwaremill.sttp.tapir" %% "tapir-akka-http-server" % "0.17.10" exclude("com.typesafe.akka", "akka-stream_2.12") ``` Now import the object: diff --git a/generated-doc/out/server/finatra.md b/generated-doc/out/server/finatra.md index cd27957cd6..e7b8e83e9a 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server" % "0.17.10" ``` and import the object: @@ -16,7 +16,7 @@ import sttp.tapir.server.finatra.FinatraServerInterpreter 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-finatra-server-cats" % "0.17.10" ``` and import the object: diff --git a/generated-doc/out/server/http4s.md b/generated-doc/out/server/http4s.md index d1a81eb12a..c41a114fb6 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-http4s-server" % "0.17.10" ``` and import the object: diff --git a/generated-doc/out/server/play.md b/generated-doc/out/server/play.md index e0cbf9f9f2..aea2719655 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-play-server" % "0.17.10" ``` 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 19f5da5a3f..ae3ea3e5de 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" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.10" ``` to use this interpreter with `Future`. @@ -83,7 +83,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" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.10" "com.softwaremill.sttp.shared" %% "fs2" % "LatestVersion" ``` to use this interpreter with Cats Effect typeclasses. @@ -164,7 +164,7 @@ val attach = route(streamedResponse) { key => Add the following dependency ```scala -"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.9" +"com.softwaremill.sttp.tapir" %% "tapir-vertx-server" % "0.17.10" "com.softwaremill.sttp.shared" %% "zio" % "LatestVersion" ``` to use this interpreter with ZIO. diff --git a/generated-doc/out/testing.md b/generated-doc/out/testing.md index 7f79f3f489..34726b51e8 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.9" +"com.softwaremill.sttp.tapir" %% "tapir-sttp-stub-server" % "0.17.10" ``` And the following imports: