Add support for data type format

[joepadmiraal]

With the Swagger 1.2 spec it is possible to add extra information about a primitive field. https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#dataTypeFormat

I would like to use this to give extra formatting information about an object that was specified as a string with -stringTypePrefixes.

I am thinking about adding adding a -typeFormats parameter which allows to specify classes with the corresponding format information. So it would look something like this.

-stringTypePrefixes com.exmachina.util.commons.keys.Key -typeFormats com.exmachina.util.commons.keys.Key key-with-numbers

Now when a Key object is used as a property it will result in this json:

{
  "id" : {
    "type" : "string",
    "format": "key-with-numbers",
    "description" : "The id of the object."
  }
}

Another option would be to create a @asString annotation and a @format annotation which can be added to the Key object in my example.

What do you think about this?

[conorroche]

i wonder would it be better to leave stringsTypePrefixes represent strings, and instead have intTypePrefixes, longTypePrefixes, booleanTypePrefixes etc?

[joepadmiraal]

I think that's another discussion, it does not solve my problem. The key-with-numbers in my example is just to illustrate some formatting text. I am not trying to represent a class with a integer value as a string. Another example could be ISO8601-date.

Also for our api's I don't immediately see a use case for representing an existing class as an boolean or integer.

[conorroche]

the format in the swagger spec is not free form, it only allows very specific values based on the type,

https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md#431-primitives

[joepadmiraal]

Ah I see it is defined that way in the 1.2 spec. The 2.0 spec is allowing it: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#data-types

If you want to keep the doclet pure 1.2 you can close this ticket.

[conorroche]

i do want to move towards 2.0 so will keep this open

[joepadmiraal]

Great, I will need to make such a change in my fork of this project. Which solution does appeal most to you? I will work with that until this project is upgraded to 2.0.

[conorroche]

I would lean towards using an @format tag for fields similar to tags like @min, @max etc for method parameters I would use @paramsFormat p1 key-with-numbers p2 date I am happy to add and leave the value as being free form but with the understanding that for 1.2 user should only choose one of the supported values and for 2.0 can be whatever you want

[conorroche]

@joepadmiraal I now support custom formats for string types using @format tag on fields and @formats on methods, for example:

/* * @formats p1 date p2 date-time / @POST public Data postData(Data data, @QueryParam(value = "p1") String p1, @QueryParam(value = "p2") String p2) { return data; }

and on a model:

/* * @format date / @SuppressWarnings("unused") private String formatFieldTag;

/* * @format date-time / public String getFormatGetterTag() { return this.formatGetterTag; }

[conorroche]

closing for 1.0.5 release

[joepadmiraal]

Thanks!