Closed slooker closed 11 months ago
Hi, @slooker !
Here, the difference between OpenAPI and Swagger about string formats. OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types Swagger: https://swagger.io/docs/specification/data-models/data-types/#string
The format 'uuid' is not supported by OAS(v3.0.2) but supported by Swagger. So you cannot use this format with apisprout 😞
@usumachi actually, according to OAS specification v3.0.2 Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.
. I suppose it means that such formats should NOT cause any errors.
@yaronius Oh, I see. You are right. Thank you for that.
@slooker I'm sorry for my wrong response.
@usumachi so how do we proceed? Removing uuid
from our specs is not an option. I'd might offer a pull request but it seems as if this validation happens outside of this project. What needs to be changed?
I reproduced the issue, the complete error message is Caught panic while trying to load: Validating Swagger failed: Unsupported 'format' value 'uuid'
. I traced this error to this code in a third-party library for parsing OpenAPI. Thus, IMO, this issue has nothing to do with the current project and should be opened in the aforementioned library.
Update: found a closed issue in the library which states the same problem, perhaps, we need to modify library usage in the current project.
JFYI opened a PR to fix this issue in the kin-openapi library https://github.com/getkin/kin-openapi/pull/96
In case this is rejected we may use
openapi3.DefineStringFormat("uuid", `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`)
before instantiating swagger loader on https://github.com/danielgtaylor/apisprout/blob/master/apisprout.go#L273
Hah, I was just stopping by to report the same problem. Unfortunately, the solution suggested in the previous comment isn't great, because it will still break for the next person who uses a custom value in format
. Would it make sense to expose this as a command line parameter? Something like:
apisprout --add-string-format uuid --add-string-format isbn ...
Looks like the discussion in getkin/kin-openapi#96 is leaning towards having us call DefineStringFormat
for everything we support. I'm open to a PR that registers the formats supported in the example generator.
What are the use cases for custom format values? For example, do other tools support the isbn
format or is it mainly for documentation?
My PR has just been merged, so we can proceed with fixing the issue. @danielgtaylor what do you think about @larsks idea to register custom formats as CLI params?
When I have a string with a format of "uuid" I get the above error.
An example is as follows: