apisprout

apisprout copied to clipboard

When I have a string with a format of "uuid" I get the above error.

An example is as follows:

     requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceSystemId:
                  type: string
                  format: uuid
                  example: dd7d8481-81a3-407f-95f0-a2f1cb382a4b

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?