swagger-api / swagger-api/swagger-ui

Support for application/x-ndjson

Open
#5,342 11 comments 20 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration

Swagger/OpenAPI definition:

---
schemes:
- http
swagger: '2.0'
host: localhost:9866
paths:
 "/foo":
   get:
     description: foo
     produces:
     - application/x-ndjson
     summary: foo
     operationId: foo
     responses:
       '200':
         description: foo
         schema:
           type: string

I've made no changes to the default Swagger-UI configuration. I'm just using the dist of v3.22.1 out-of-the-box.

Is your feature request related to a problem?

I've been trying to document an application that returns content-type: application/x-ndjson. The format is spec'ed here. An example response:

{"hello": "world"}

{"goodbye": "world"}

When I render my spec in Swagger UI out-of-the-box and click Try It Out > Execute, Swagger UI seems to try and fail to treat the response data as JSON, giving an error message:

image

I can see by peeking in swagger-ui-bundle.js where it seem to be treating any content-type that contains json as JSON:

                    else if (/json/i.test(n)) {
                        try {
                            m = (0, r.default)(JSON.parse(t), null, "  ")
                        } catch (e) {
                            m = "can't parse JSON.  Raw result:\n\n" + t
                        }

I'm no JavaScript pro, but I found that if I hack this to exclude my data type, now it silently renders it as text.

                    else if (/json/i.test(n) && !/x-ndjson/i.test(n)) {
                        try {
                            m = (0, r.default)(JSON.parse(t), null, "  ")
                        } catch (e) {
                            m = "can't parse JSON.  Raw result:\n\n" + t
                        }

image

Describe the solution you'd like

It would be lovely if Swagger UI actually parsed x-ndjson according to its spec. But at minimum, it would be an improvement if it just didn't report an error message due to trying to parse it as JSON, similar to what I've done with my hack.

Contributor guide

Open the contributing guide

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

Reproduce the response rendering with the provided Swagger/OpenAPI definition and inspect the content-type handling shown in swagger-ui-bundle.js. Verify that an application/x-ndjson response is displayed without a JSON parse error, ideally according to the linked NDJSON specification.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
frontend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.