Extension library for Tapir and MUnit that allows golden-testing Tapir endpoints' OpenAPI documentation.
Add the following line to your build.sbt file:
libraryDependencies += "com.alejandrohdezma" %% "tapir-golden-openapi-munit" % "2.0.0" % TestGiven this endpoint definition...
import sttp.tapir._
val myEndpoint = endpoint.get
.in("v1" / "users" / path[String]("user_id"))
.in(query[Int]("size"))
.out(stringBody)
.errorOut(stringBody)In order to golden-test the generation of the OpenAPI documentation you just need to create a new suite extending TapirGoldenOpenAPISuite and override the list of endpoints:
class EndpointsSuite extends munit.TapirGoldenOpenAPISuite {
override val endpoints: List[AnyEndpoint] = List(myEndpoint)
}Running this suite the first time will generate the following file under resources/openapi.yaml.
Important! You should always commit this file. If this generation process is called from CI the test will fail.
See the generated OpenAPI file
# This file has been autogenerated, don't try to edit it manually
openapi: 3.0.3
info:
title: ''
version: ''
paths:
/v1/users/{user_id}:
get:
operationId: getV1UsersUser_id
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: size
in: query
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
text/plain:
schema:
type: string
'400':
description: 'Invalid value for: query parameter size'
content:
text/plain:
schema:
type: string
default:
description: ''
content:
text/plain:
schema:
type: stringThere are available some methods that can be overriden to alter the generated file:
tapirGoldenOpenAPIInfo: The info that will be used when generating the OpenAPI file.tapirGoldenOpenAPIOptions: The options that will be used when generating the OpenAPI file.tapirGoldenOpenAPIHeader: The value of this header will be prepended to the generated YAML file.tapirGoldenOpenAPIFileName: Name of the generated file with the OpenAPI documentation.tapirGoldenOpenAPIPath: Folder where the OpenAPI file will be generated. Defaults to theresourcefolder.
import java.nio.file.Path
import sttp.apispec.openapi.Info
import sttp.tapir._
import sttp.tapir.docs.openapi.OpenAPIDocsOptions
class AllModificationsSuite extends munit.TapirGoldenOpenAPISuite {
override def tapirGoldenOpenAPIPath: Path = super.tapirGoldenOpenAPIPath.resolve("yaml")
override def tapirGoldenOpenAPIOptions: OpenAPIDocsOptions =
OpenAPIDocsOptions.default.copy(defaultDecodeFailureOutput = _ => None)
override def tapirGoldenOpenAPIFileName: String = "open-api.yaml"
override def tapirGoldenOpenAPIInfo: Info = Info("title", "version", Some("description"))
override def tapirGoldenOpenAPIHeader: String = "# This is a header"
override val endpoints: List[AnyEndpoint] = List(myEndpoint)
}This suite ☝️ will generate the file open-api.yaml under resources/yaml.
See the generated OpenAPI file
# This is a header
openapi: 3.0.3
info:
title: title
version: version
description: description
paths:
/v1/users/{user_id}:
get:
operationId: getV1UsersUser_id
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: size
in: query
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
text/plain:
schema:
type: string
default:
description: ''
content:
text/plain:
schema:
type: stringIf you also want to validate the generated OpenAPI you can do the following:
- Add
tapir-golden-openapi-munit-validatorto yourbuild.sbt:
libraryDependencies += "com.alejandrohdezma" %% "tapir-golden-openapi-munit-validator" % "2.0.0" % Test- Extend your suite with
TapirGoldenOpenAPIValidatorSuite:
class ValidatedEndpointsSuite
extends munit.TapirGoldenOpenAPISuite
with munit.TapirGoldenOpenAPIValidatorSuite {
override val endpoints: List[AnyEndpoint] = List(myEndpoint)
} |
 |
 |
|---|---|---|
| alejandrohdezma | AdrianRaFo | gutiory |