# OpenAPI documentation for custom DecodeFailureHandler

**URL:** <https://softwaremill.community/t/openapi-documentation-for-custom-decodefailurehandler/106>\
**Category:** tapir\
**Created:** [January 26, 2023, 1:50pm UTC](https://softwaremill.community/t/openapi-documentation-for-custom-decodefailurehandler/106 "2023-01-26T13:50:46Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![korlowski](https://dub1.discourse-cdn.com/flex005/user_avatar/softwaremill.community/korlowski/32/84_2.png) [@korlowski](https://softwaremill.community/u/korlowski)\
**Post date:** [January 26, 2023, 1:50pm UTC](https://softwaremill.community/t/openapi-documentation-for-custom-decodefailurehandler/106/1 "2023-01-26T13:50:46Z")

</div>

Hi, my application returns errors in a standardized format, a class `com.example.Fail`. I’m using `TapirJsonCirce` to derive a `Codec` and a `Schema` for it. When I specify this error type in the endpoint and then explicitly return it as error in the endpoints, everything works as expected. I get a nice error message from the API that is correctly documented in OpenAPI.

I’ve gone a step further and defined a custom `DecodeFailureHandler` so that all decode failures are also returned in this error format. As far as the API goes, it works perfectly, and when I send an bad request, my request is handled by the code I’ve written, and I get a nice `com.example.Fail` response like:

```auto
{"errors":[{"code":"INVALID_PATH_PARAM","message":"Invalid value for: path parameter item-id: Some(UUID string too large)"}],"timestamp":1674737764093}

```

I’ve figured out that in order to correctly document these responses in the OpenAPI documentation, I need to also configure `defaultDecodeFailureOutput: EndpointInput[_] => Option[EndpointOutput[_]] ` in `OpenAPIDocsOptions`. I’ve made it return something like:

```auto
Some(statusCode(StatusCode.BadRequest) and jsonBody[com.example.Fail])

```

This _almost_ works. The OpenAPI doc picks up the new response (and I can successfully set descriptions and examples), but the schema is broken. The `$ref` contains the class name instead of a reference to the correct type:

```auto
'400':
  content:
    application/json:
      schema:
        $ref: com.example.Fail

```

instead of:

```auto
'400':
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Fail'

```

I’ve used `SwaggerInterpreter`’s `customiseDocsModel` to manually fix the references but that’s hacky. Is there something else I can do to fix this?

---

<div class="post-metadata">

**Author:** ![adamw](https://dub1.discourse-cdn.com/flex005/user_avatar/softwaremill.community/adamw/32/28_2.png) [@adamw](https://softwaremill.community/u/adamw)\
**Post date:** [February 7, 2023, 3:36pm UTC](https://softwaremill.community/t/openapi-documentation-for-custom-decodefailurehandler/106/2 "2023-02-07T15:36:57Z")

</div>

Indeed, good catch, this was a bug. PR fixing this is here: [Properly generate docs for default error responses defined in options by adamw · Pull Request #2717 · softwaremill/tapir · GitHub](https://github.com/softwaremill/tapir/pull/2717)