softwaremill / softwaremill/tapir

[BUG] The OpenAPIDocsInterpreter does not generate a correct YAML for a Tapir endpoint with oneOf output

Open
#3,152 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Scala
Stars
1.5k
Forks
468
Avg merge
5h 37m
Merged PRs (30d)
34

Description

Tapir version: 1.7.3

Scala version: 3.3.0 and 2.13.x

Describe the bug
The OpenAPIDocsInterpreter does not generate a correct YAML for a Tapir endpoint that uses oneOf in its output.

How to reproduce?

Minimal reproduction:

//> using scala 3.3
//> using lib "com.softwaremill.sttp.tapir::tapir-core:1.7.3"
//> using lib "com.softwaremill.sttp.tapir::tapir-json-circe:1.7.3"
//> using lib "com.softwaremill.sttp.tapir::tapir-openapi-docs:1.7.3"
//> using lib "com.softwaremill.sttp.apispec::openapi-circe-yaml:0.6.0"

import io.circe.generic.auto.*
import sttp.apispec.openapi.OpenAPI
import sttp.apispec.openapi.circe.yaml.*
import sttp.tapir.*
import sttp.tapir.docs.openapi.OpenAPIDocsInterpreter
import sttp.tapir.json.circe.*
import sttp.tapir.generic.auto.*

object TapirBugExample extends App:
  case class First(value: Int)
  case class Second(value: String)

  val endpointOutput =
    oneOf(
      oneOfVariant(jsonBody[First]),
      oneOfVariant(jsonBody[Second])
    )

  val testEndpoint =
    endpoint
      .in("demo")
      .out(endpointOutput)

  val docs: OpenAPI = OpenAPIDocsInterpreter().toOpenAPI(testEndpoint, "test", "1.0").openapi("3.0.3")

  println(docs.toYaml3_0_3)

This code, when run with scala-cli, produces the following output:

openapi: 3.0.3
info:
  title: test
  version: '1.0'
paths:
  /demo:
    get:
      operationId: getDemo
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Second'
components:
  schemas:
    First:
      required:
      - value
      type: object
      properties:
        value:
          type: integer
          format: int32
    Second:
      required:
      - value
      type: object
      properties:
        value:
          type: string

The First type is missing from the responses section of the /demo path.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the minimal Scala reproduction and the OpenAPIDocsInterpreter().toOpenAPI entry point, using the Tapir 1.7.3 dependencies shown. Compare the generated YAML for the oneOf output with the expected response schema; done means the /demo response represents both First and Second rather than only Second.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, scala
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.