You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by GitBox <gi...@apache.org> on 2022/01/29 06:38:08 UTC
[GitHub] [iceberg] kbendick opened a new pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible
kbendick opened a new pull request #4004:
URL: https://github.com/apache/iceberg/pull/4004
I've been using various swagger & open-api CLI tools to validate the OpenAPI spec doc as we've been working on it.
I have yet to find one that I love, or that is considered "canonical", so I tend to use a handful of them as well as reference the spec. Some of the tools Ive been using include `widdershins` and others from https://openapi.tools/
For the `example` values in `schema` components, they are allowed to be expressed as a single string according to the spec (namely if they can't be properly expressed as JSON or YAML). However, some tools struggle to parse these properly and thus render the example as an explicit string.
Given that these examples can be expressed as JSON or YAML, I've updated the ones I've noticed giving trouble.
While these are technically allowed, the require care in escaping that adds unneeded complexity, and some tools still struggle anyway. Note that editor.swagger.io doesn't fail on these, but some 3rd party tools do. These examples are arguably more correct anyway as JSON / YAML.
What the docs have to say on this: https://swagger.io/specification/
```
example ... A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
```
--
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
[GitHub] [iceberg] kbendick edited a comment on pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible
Posted by GitBox <gi...@apache.org>.
kbendick edited a comment 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!
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 file once a good CLI tool is determined. Everything I've found so far is installed via `npm` or `pip` and I haven't been able to determine if there's consensus around the best tool (or even top 3 best CLI tools). I'm not one to dive right in on bringing in an `npm` based dependency without some research.
It's presently valid per `editor.swagger.io` - which is a paid / enterprise tool (with a free tier) which focuses in this space (open api docs). 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 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
[GitHub] [iceberg] kbendick edited a comment on pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible
Posted by GitBox <gi...@apache.org>.
kbendick edited a comment 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
[GitHub] [iceberg] rdblue merged pull request #4004: SPEC - Convert string typed examples to JSON in REST API
Posted by GitBox <gi...@apache.org>.
rdblue merged pull request #4004:
URL: https://github.com/apache/iceberg/pull/4004
--
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
[GitHub] [iceberg] kbendick commented on pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible
Posted by 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
[GitHub] [iceberg] kbendick edited a comment on pull request #4004: REST Catalog OpenAPI Doc - Convert string type examples to JSON / YAML where possible
Posted by GitBox <gi...@apache.org>.
kbendick edited a comment 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.
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 file once a good CLI tool is determined. Everything I've found so far is installed via `npm` or `pip` and I haven't been able to determine if there's consensus around the best tool (or even top 3 best CLI tools).
It's presently valid per editor.swagger.io - which is a paid / enterprise tool (with a free tier) which focuses in this space (open api docs). 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 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