[GitHub] [iceberg] kbendick commented on pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible

[GitBox <gi...@apache.org>]

kbendick commented on pull request #4004:
URL: https://github.com/apache/iceberg/pull/4004#issuecomment-1025060021


   > Great, looks more consistent
   
   It also parses better in various CLI tools outside of editor.swagger.io.
   
   But this fixes some parsing output in a CLI tool  `widdershins` that can convert the OpenAPI document to markdown based documentation, with examples of each call in choices of several languages - the bash / `curl` examples are the best as far as documentation is concerned. Widdershins can be installed via `npm install -g widdershins`.
   
   As a follow up, I intend to add some documentation about using some of these tools, and ideally a github action to validate the specification once a good CLI tool is determined. It's presently valid per editor.swagger.io - which is a paid / enterprise tool (with a free tier). So I'm continuing to use editor.swagger.io as the canonical validation tool, but fixing things that could be made better for parsing in various other tools.
   
   So this is a step in that direction, as well as looking more consistent. 🙂 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org