Forum Discussion

fastdude7's avatar
fastdude7
New Contributor
5 years ago

Specifying types which are subset of String

Hi, I would like to specify an API which returns a FooId. A FooId is a 4 character String consisting of ascii alphanum chars.

When I end up generating my API I make it so that the FooId is not a wrapper for a string instead I just return:

{
    fooId: "abcd",
    someThingElse: "a",
    number: 2
}

Is it possible to specify in the swagger doc (openAPI) that:

  • A FooId should be treated like a string, no wrapping class for example.
  • While preserving the fact that it is a FooId so a client consuming the swagger doc knows which APIs really return strings and which ones are returning a FooId, so no information is lost.

Does the spec support this?

 

full disclosure I asked a similar question on stack overflow which got no responses https://stackoverflow.com/questions/55915610/does-swagger-openapi-support-declaring-types-that-are-sub-types-of-string-or-o

 

3 Replies

Sort By
    • fastdude7's avatar
      fastdude7
      New Contributor
      5 years ago

      Hi,
      So I assume:

          ssn:
      type: string
      pattern: '^\d{3}-\d{2}-\d{4}$'

      this is defining something like what I want, where the type is 'ssn' but it is really just a string.

      If I was to have a list of `ssn` could it look like:

      ["AAA-GG-SSSS","AAA-GG-SSSS","AAA-GG-SSSS"]

      ie no wrapping class.
      So should this mean that something like:

      "schema": {
    "type": "array",
    "items": {
        "$ref": "#/definitions/FooId"
    }

      and in definitions 

      "FooId": {
    "type": "string",
    "title": "FooId"
},

      would work to define an array of FooId where FooId is really just a string type. When the API responds that looks like:

      ["abcd", "abcd"]

      If this is the case then it looks like at least the standard supports. So now I need to find out why springfox is not making those types.

      Was this supported in version 2?

      • fastdude7's avatar
        fastdude7
        New Contributor
        5 years ago

        Hi so in the end what I am doing is generating types in the definitions section like so:

        FooId : {
     "type": "string",
     "title": "CollectionId"
}

        the swagger API UI seems to be happy with that, and I assume that is legit.