Strange behaviour with Swagger documentation output
Having trouble installing Oxygen? Got a bug to report? Post it all here.
Strange behaviour with Swagger documentation output
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.
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.
. 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
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 3191 times
- image.png (27.77 KiB) Viewed 3191 times
Thank you,
Seema
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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:
Best regards,
Cosmin
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:
- 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"
- In the view, search for the "/stylesheets/open-api/openAPI_v2.0_to_v3.0.xsl" file and open it in the main editor
- Go to line 180 and delete the following line:
Code: Select all
<xsl:apply-templates select="node()[not(schema)]" mode="convertV2"/>
- Save the file and restart Oxygen
Best regards,
Cosmin
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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?
Thank you,
Seema
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 3134 times
Seema
Last edited by Seema on Mon Mar 13, 2023 6:04 pm, edited 1 time in total.
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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
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
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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
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
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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
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
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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.
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?
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
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 3031 times
- image.png (83.01 KiB) Viewed 3031 times
- image.png (250.35 KiB) Viewed 3031 times
- image.png (103.21 KiB) Viewed 3031 times
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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
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
- Attachments
-
- image.png (14.18 KiB) Viewed 3004 times
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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 messages for error codes that we were looking to display on separate lines, however, continue to display in a single para.
Thank you,
Seema
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 2934 times
- image.png (136.47 KiB) Viewed 2934 times
Seema
- Attachments
-
- image.png (73.97 KiB) Viewed 2934 times
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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:
Best regards,
Cosmin
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
Cosmin
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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.
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.
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.
- No space before the backward slash
- Tried this with and without a space before the backward slash
- Tried this with and without a space before the backward slash
Not sure what I am missing or if I am inputting the syntax incorrectly.
Thank you,
Seema
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 2872 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 2872 times
Code: Select all
The following list outlines the possible error messages:\n\nEPAERR3101
Code: Select all
The following list outlines the possible error messages: \nEPAERR3101
Code: Select all
The following list outlines the possible error messages: \\nEPAERR3101
Code: Select all
The following list outlines the possible error messages: \n\n EPAERR3101
Thank you,
Seema
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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:
Best regards,
Cosmin
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:
- I opened the JSON file that you sent us in Oxygen.
- 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.
- I published the map that referenced the OpenAPI JSON file and the error that I modified was presented on a new line.
Best regards,
Cosmin
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Re: Strange behaviour with Swagger documentation output
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
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
Re: Strange behaviour with Swagger documentation output
Hello,Cosmin Duna wrote: ↑Mon Mar 13, 2023 5:23 pm 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:After these steps, the dynamic conversion on publishing should not lose the description from responses.
- 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"
- In the view, search for the "/stylesheets/open-api/openAPI_v2.0_to_v3.0.xsl" file and open it in the main editor
- Go to line 180 and delete the following line:
Code: Select all
<xsl:apply-templates select="node()[not(schema)]" mode="convertV2"/>
- Save the file and restart Oxygen
Best regards,
Cosmin
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
-
- Site Admin
- Posts: 123
- Joined: Wed Dec 12, 2018 5:33 pm
Re: Strange behaviour with Swagger documentation output
Post by 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
Unfortunately, the fix didn't catch version 25.1 of Oxygen but it will be included in the upcoming version 26.
Best regards,
Cosmin
Cosmin Duna
<oXygen/> XML Editor
http://www.oxygenxml.com
<oXygen/> XML Editor
http://www.oxygenxml.com
Jump to
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen JSON Editor
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service