danielgtaylor / huma

Huma REST/HTTP API Framework for Golang with OpenAPI 3.1
https://huma.rocks/
MIT License
1.87k stars 138 forks source link

Add contentMediaType field to generated schema when format is binary #422

Closed lsdch closed 4 months ago

lsdch commented 4 months ago

This PR adds the contentMediaType property to the generated schema spec for binary field. This is mainly for the purpose of compatibility with API documentation tools such as Stoplight Elements (see #397).

Note that #415 sets contentType property in the schema, but that is not sufficient for Stoplight to show the file upload UI component, event though the OpenAPI spec says contentMediaType is not required when contentType is defined. Although that may rather be an issue in Stoplight, in my understanding it does not hurt to add this redundancy to Huma.

Thus, this PR can be considered independently from #415. I hope I'm not mistaken about what the OpenAPI specs say, let me know if you think this rather belongs to Stoplight issues.

Example schema:

{
  "requestBody": {
    "content": {
        "multipart/form-data": {
            "schema": {
                "properties": {
                    "filename": {
                        "contentMediaType": "application/octet-stream",
                        "description": "filename of the file being uploaded",
                        "format": "binary",
                        "type": "string"
                    },
                    "name": {
                        "description": "general purpose name for multipart form value",
                        "type": "string"
                    }
                },
                "type": "object"
            }
        }
    },
    "required": true
}

Sample UI screenshot: image

codecov[bot] commented 4 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 92.74%. Comparing base (a93ebe6) to head (a1757e6). Report is 5 commits behind head on main.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #422 +/- ## ========================================== + Coverage 92.72% 92.74% +0.02% ========================================== Files 21 21 Lines 3546 3556 +10 ========================================== + Hits 3288 3298 +10 Misses 220 220 Partials 38 38 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.