Redocly / Redocly/redocly-cli

Values ending in space or newline get odd treatment by bundle and join

Open
#834 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

c0 p3 Type: Enhancement
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Describe the bug
I have some multiline descriptions in my OpenAPI schemas. Here's an example of a tag description:

tags:
  - name: Contacts
    description: |
      You can think of contacts as a common, shared address book that's used across a company by many people for a variety of purposes. Contacts hold all the information needed to contact an individual or business, including name, email address, phone number, mailing address, and more. 
      
      Contacts are almost always used with other Sage Intacct objects, such as vendors, customers, or locations. For example, you specify a contact in Order Entry and Purchasing transactions to set a ship-to, bill-to, pay-to, or return-to addresses, and to determine tax on transactions.

servers:
  - url: 'http://localhost:3000'

Notice the empty line at the end of the description. That--or if the last character is a space instead of new line--results in strange output from the bundle and join operations. Here is the result after bundle:

tags:
  - name: Contacts
    description: "You can think of contacts as a common, shared address book that's used\nacross a company by many people for a variety of purposes. Contacts hold\nall the information needed to contact an individual or business, including\nname, email address, phone number, mailing address, and more. \n\n\nContacts are almost always used with other Sage Intacct objects, such as\nvendors, customers, or locations. For example, you specify a contact in\nOrder Entry and Purchasing transactions to set a ship-to, bill-to, pay-to,\nor return-to addresses, and to determine tax on transactions.\n"
servers:
  - url: http://localhost:3000

Notice that it's no longer a multi-line text field, is wrapped in quotes, and \n has been inserted where it thinks there need to be line breaks (which may be based on a max line length setting?) .

In one sense this is just an aesthetic issue, as the display of the field looks the same in Redocly. But it looks pretty odd when I go in and look at the file after bundling. I'd call it a minor bug.

To Reproduce
Steps to reproduce the behavior:

  1. Create an OpenAPI file with a multi-line description field. Put a space or a newline at the end of the field.
  2. Run redocly bundle on the file. I think redocly merge does the same thing, but you need multiple files to test that.
  3. Look at the description field in the bundled file.

Expected behavior
The description field should still be a multi-line text field, without inserted newlines. It's fine to trim any extra white space off the end.

Redocly Version(s)
1.0.0-beta.102

Node.js Version(s)
v18.7.0

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

Start by reproducing the issue with the redocly bundle command described, then compare the bundle and join processing paths for multiline descriptions ending in a space or newline. Done means trailing whitespace may be trimmed, but the description remains a multiline text field without inserted newlines or unexpected quoting.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.