softwaremill/tapir v0.19.0

on GitHub

New features

Security

This release focus on security improvements, most notably extending Endpoint with an additional type parameter A for security inputs. In case security endpoints are defined, the security logic has to be provided first, followed by the server logic. Moreover, error outputs can be extended for partial endpoints by adding new error output variants.

More information on the change:

• security and server logic documentation
• ADR on the security refactoring
• Auth / security enhancements GH issue

Other

• cats-effect 3 & http4s 0.23 support; cats-effect 2 support is dropped
• static file serving support
• Netty server interpreter
• more flexible oneOf outputs, which now allow arbitrary outputs, without the need to provide a status code
• .errorOutVariant for extending error outputs with new variants
• endpoints with authentication can be hidden by returning a 404 instead of a 401 when an alternate DecodeFailureHandler is used

Migrating from previous versions

• replace any occurrence of the Endpoint type with PublicEndpoint
• replace ServerEndpoint[I, E, O, R, F] with ServerEndpoint[R, F] (e.g. ServerEndpointp[Any, Future]), or with ServerEndpoint.Full[Unit, Unit, I, E, O, R, F] if you need to preserve the types of inputs/outputs
• replace any calls to server interpreter which provided the endpoint and server logic separately, with a call to one of the .serverLogic variants. For example, AkkaHttpServerInterpreter().toRoute(helloWorld)(name => Future.successful(Right(s"Hello, $name!"))) should be replaced with AkkaHttpServerInterpreter().toRoute(helloWorld.serverLogicSuccess(name => Future.successful(s"Hello, $name!"))).

This should make the code compile using the new version. The next step would be to move security-related inputs from .in to .securityIn when defining the endpoint, and taking advantage of the security improvements (e.g. separate security and server logic).

Other breaking changes

• server interpreters accept only ServerEndpoints. Replace .toRoute(endpoint)(logic) with .toRoute(endpoint.serverLogic(logic))
• serverLogicInfallible is renamed to serverLogicSuccess
• ServerLog implementations has an extended interface - the whole request is now available
• there's are single swagger & redoc modules, see OpenAPI docs
• specifying custom interceptors is unified across all server interpreters. Previous usages of [Interpreter]ServerOptions.customInterceptors(...) should be replaced with .customInterceptors.[builderMethods]().options
• ZEndpoint is removed, ZServerEndpoint is extended with capabilities
• a 405 is returned if multiple endpoints are being interpreted as a server, the request matches the path of some endpoint but not the method

Deprecations

• oneOfMapping is renamed to oneOfVariant

Towards a stable release

The current plan is to have two more cycles before a stable release: 0.20 and then 1.0, both with a milestone/RC phase.

A stable 1.0 release will mean that core should not change until the next version in a binary-incompatible way - we have MiMA for that already set up. Other integration modules won't have this requirement as they depend on the integrations, so it would be hard to make any promises.

Hence - vote for the issues that you'd like fixed/implemented first and foremost, and let us know if you'd see any needs for breaking changes in core!

Changes since 0.19.0-M16

• Mapping over errors in partial server endpoints (#1623) @adamw
• Properly handle decode failures of both regular & security inputs (#1622) @adamw
• use addSegment instead of addPath for http4s (#1621) @yurique
• Improve how error output variants are defined: fix ordering, provide a method which allows arbitrary ordering (#1620) @adamw
• Enables hiding endpoints with auth inputs if any inputs fails to decode (#1615) @adamw
• ServerLog refactoring (#1598) @micossow
• Improve refined integration for constraint on string size (#1613) @strokyl
• Add swagger and redoc bundles, which allow interpreting and exposing docs in a single step (#1611) @adamw
• Encode possible values when reporting an enumeraton error in the DefaultDecodeFailureHandler (#1608) @adamw
• Add endpoint as a parameter to the OpenAPIDocsOptions (#1609) @adamw
• Rename httpMethod to method and move to EndpointMetaOps (#1607) @adamw
• Header values in Codec, codec naming cleanup (#1606) @adamw
• Fix http4s WebSocket headers (#1601) @ghostdogpr

Dependency updates since 0.19.0-M16

• Update jawn-parser to 1.3.0 (#1614) @scala-steward
• Update scalafmt-core to 3.1.1 (#1612) @scala-steward
• Update derevo-core to 0.12.7 (#1610) @scala-steward
• Update opentelemetry-api, ... to 1.9.0 (#1605) @scala-steward
• Update logback-classic, logback-core to 1.2.7 (#1604) @scala-steward