Strange behaviour with Swagger documentation output

[Seema]

Hello,
I am generating Swagger API documentation, and I am currently using the dynamic OpenAPI to Dita converter to convert our JSON files to DITA. However, I am encountering a strange behaviour in the generated PDF output. For example when I edit the documentation in the Swagger Editor, it displays my changes in the editor. In the example below, the text under response code 400 is visible both in the JSON file and the swagger editor.

image.png (63.33 KiB) Viewed 3188 times

However, in the PDF output generated using the the OpenAPI to DITA converter, it does not display the text under the response codes, but just links to the references included in the JSON.

image.png (27.77 KiB) Viewed 3188 times

. I am wondering what could be possibly causing this behaviour. The JSON file doesn't flag any obvious errors in the syntax that might be causing this. Please, could you share any insight into this issue I am encountering. I am trying to attach the JSON file here for reference, but it's not allowing me to attach a JSON file. I get an error saying Invalid file extension.
Thank you,
Seema

[Cosmin Duna]

Hi,
Thank you for reporting this problem.
I created a sample using the screenshot you provided, I reproduced the problem and I registered an internal issue for this.
Please do the following steps for correcting the conversion in your application:

1. Open the following jar file into the "Archive Browser" view from Oxygen: "Oxygen_install_dir\frameworks\dita\DITA-OT3.x\plugins\com.oxygenxml.dynamic.resources.converter\lib\oxygen-batch-converter-core.jar"
2. In the view, search for the "/stylesheets/open-api/openAPI_v2.0_to_v3.0.xsl" file and open it in the main editor
3. Go to line 180 and delete the following line:

   Code: Select all

   <xsl:apply-templates select="node()[not(schema)]" mode="convertV2"/>

4. Save the file and restart Oxygen

After these steps, the dynamic conversion on publishing should not lose the description from responses.

Best regards,
Cosmin

[Seema]

Hello,
Thank you for suggesting the workaround. However, when I open that file in the editor, it opens with a fatal error (screenshot attached for reference). And further, when I remove the content from line 180 and try to save the file, I get another error and I am unable to save the file with that change included. Is there anything I need to do to be able to save that file?

image.png (124.75 KiB) Viewed 3131 times

Thank you,
Seema

[Cosmin Duna]

Hi Seema,

The saving error may be caused by the fact that you don't have the necessary permissions to edit files in the 'C' drive.
I will send you an email with the edited jar file and you can try to replace it using Windows File Explorer.

Best regards,
Cosmin

[Seema]

Hi Cosmin,

Thanks for sending the edited file.
Unfortunately, our anti-virus policy quarantined your email with the attachment.
So, as a workaround, I uninstalled and then reinstalled Oxygen Author in the C drive but outside the Program Files folder. That seemed to do the trick. After changing the install location, I was able to edit file as suggested in the workaround and then save it. I ran the transform after applying the workaround and it is now working fine. I can now see the content under response codes along with the referenced links.

Thank you,
Seema

[AnnetteSo]

Hi Cosmin, many thanks for that, we've applied the workaround now and it's resolved the issue.

[Cosmin Duna]

Hi,

I'm glad to hear that the problem has been resolved. If you encounter any other issues, please don't hesitate to let us know.

Best regards,
Cosmin

[Seema]

Hello Cosmin,
With respect to the Swagger documentation, I applied that workaround and the content under response codes is now showing. However, with respect to formatting, I was hoping to display each error code on a separate line, the way it appears in the Swagger editor.

image.png (109.59 KiB) Viewed 3028 times

But when I use the dynamic OpenAPI to DITA converter to generate the Swagger documentation, in the PDF, the error codes are all displayed in one single para. Is there anything I can do to display the formatting the way it appears in the Swagger editor?

image.png (83.01 KiB) Viewed 3028 times

Also, with the workaround applied, while I can now see the content under response codes, some other content under API calls is now missing. Please see the two screenshots below. The highlighted content appears in the JSON file and the Swagger editor but missing from the PDF. Is there anything I need to do to display that content. Thank you

image.png (250.35 KiB) Viewed 3028 times

image.png (103.21 KiB) Viewed 3028 times

[Cosmin Duna]

Hi,
For the second problem, there is an end tag for the 'strong' element in the description that doesn't have a corresponding start tag. Our Markdown conversion seems to be having issues with this. I will register an internal issue to make the conversion of the Markdown description more flexible.
Additionally, the code blocks are not being formatted correctly. You should use the following syntax to indicate the start and end of a code block: https://www.markdownguide.org/extended- ... ghlighting.
Like in the attached image.

I am unable to reproduce the first problem. Could you please check if there are any other HTML tags that are not closed correctly in that description? If possible, could you send us a small sample where this problem can be reproduced? You can send it to us via email at: support@oxygexml.com

Best regards,
Cosmin

[Seema]

Hi Cosmin,
Thank you for letting me know about the code formatting.
For the other issues, I will send you the sample file by email.
Thank you,
Seema

[Seema]

Update:
We removed the closing </strong> tag which didn't have a corresponding start <strong> tag from the description. That seems to have resolved at least two issues for us:

• The content that was not displaying in the API calls is now displaying

• Code block is displaying correctly too now after removing the closing </strong> tag

image.png (98.73 KiB) Viewed 2931 times

The messages for error codes that we were looking to display on separate lines, however, continue to display in a single para.

image.png (136.47 KiB) Viewed 2931 times

Thank you,
Seema

[Cosmin Duna]

Hi Seema,
Our converter expected to find markdown in those descriptions. The OpenAPI from the screenshot, in the YAML format, uses blank lines to separate paragraphs. The converter handles correctly this syntax. Note that you can also dynamically convert OpenAPI in YAML format in Oxygen.

The sample sent by email is in JSON format and has some soft line breaks (https://github.github.com/gfm/#soft-line-breaks) which our conversion process as white spaces. For separating paragraphs, please add extra new lines like this:

Code: Select all

possible error messages: \n\nEPAERR3101

Best regards,
Cosmin

[Seema]

Hi Cosmin,
Thank you for your response.
The screenshot that I had attached to my previous post was actually from the JSON file itself (the same sample file I sent in my email) and not YAML. For this project, all of our API documentation is in JSON. In the screenshot, I had my JSON file open in the Swagger editor, just to demonstrate the contents in the JSON file and how they appear in the editor.

Many thanks for that newline syntax to include into the JSON file. I tried applying that syntax to the error codes to try and display them on separate lines. Unfortunately, I have not had much luck in achieving the output in the desired format. Please see the screenshots below of the JSON file open in the Swagger editor and that of the generated PDF output.

image.png (77.42 KiB) Viewed 2869 times

For the time being, I have applied the syntax only to one error message, just to see if that error message would show on a separate line. But this is how it is displayed in the output.

image.png (74.65 KiB) Viewed 2869 times

Aside from the above, I tried incorporating the newline syntax in these forms, based on discussions in a few forums to see if that would work. But the following attempts have also been unsuccessful.

Code: Select all

The following list outlines the possible error messages:\n\nEPAERR3101

- No space before the backward slash

Code: Select all

The following list outlines the possible error messages: \nEPAERR3101

- Tried this with and without a space before the backward slash

Code: Select all

The following list outlines the possible error messages: \\nEPAERR3101

- Tried this with and without a space before the backward slash

Code: Select all

The following list outlines the possible error messages: \n\n EPAERR3101

Not sure what I am missing or if I am inputting the syntax incorrectly.
Thank you,
Seema

[Cosmin Duna]

Hi Seema,
When you paste JSON content into the Swagger editor, it prompts you if you want to convert it to YAML. The content from your screenshot seems to be converted.
Here are the steps that I did on my side, which worked:

1. I opened the JSON file that you sent us in Oxygen.
2. I searched for the first error message inside the document and instead of "\nEPAERR3101", I added, "\n\nEPAERR3101". Note that you can text "\n* EPAERR3101" for presenting them in a bullet list.
3. I published the map that referenced the OpenAPI JSON file and the error that I modified was presented on a new line.

I think the Swager editor might have escaped "\n" when you saved the modified file back as JSON.

Best regards,
Cosmin

[Seema]

Hi Cosmin,
I see what you mean now. Thanks for pointing that out. I usually import the file into the Swagger editor instead of pasting the contents, and although I did not get any prompt about the YAML conversion while importing the file, it may be possible that it converted the file to YAML when I imported it. After I finish editing the file, I save the updated file as JSON.
I followed your method and edited the file in Oxygen this time instead of the Swagger editor. And when I updated the error messages with the newline syntax "\n\n", I was able to display the error messages on separate lines.
Many thanks for this solution
Thank you,
Seema

[Seema]

Hi,
Thank you for reporting this problem.
I created a sample using the screenshot you provided, I reproduced the problem and I registered an internal issue for this.
Please do the following steps for correcting the conversion in your application:

1. Open the following jar file into the "Archive Browser" view from Oxygen: "Oxygen_install_dir\frameworks\dita\DITA-OT3.x\plugins\com.oxygenxml.dynamic.resources.converter\lib\oxygen-batch-converter-core.jar"
2. In the view, search for the "/stylesheets/open-api/openAPI_v2.0_to_v3.0.xsl" file and open it in the main editor
3. Go to line 180 and delete the following line:

   Code: Select all

   <xsl:apply-templates select="node()[not(schema)]" mode="convertV2"/>

4. Save the file and restart Oxygen

After these steps, the dynamic conversion on publishing should not lose the description from responses.

Best regards,
Cosmin

Hello,
I just wanted to ask if there are any plans to include the above workaround as a code fix? At present, I manually apply the workaround whenever I update Oxygen Author to the latest version.
Thank you,
Seema

[Cosmin Duna]

Hi Seema,

Unfortunately, the fix didn't catch version 25.1 of Oxygen but it will be included in the upcoming version 26.

Best regards,
Cosmin

[Seema]

Thank you, Cosmin.