How to specify format of the field?

[mgwoj]

In the specification it is possible to add to the field of type string, that its format it date or date+time. For example

                   entryTime:
                      type: string
                      format: date-time
                      description: time of entry
 

How to achieve that with this plugin?

[mduesterhoeft]

This is not yet covered. At the moment we only care about the type in the schema. But the format would also be very valuable. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypes

What do you think - do you have an idea on how to implement this? Maybe you can even file a PR?

[mgwoj]

What about adding new property format (similar to type) to FieldDescriptor class? This property could accept a string or even better, some enum with values like int32, int64, string, date, etc. and then during generating the contract file it could be added along type value. Other option is to add property which accepts "common names" and based on that it generates proper values for type and format based on the table in the specification.

[mduesterhoeft]

Extending the FieldDescriptor sounds like a good solution. Do you want to give it a try?

[mgwoj]

Probably not with Kotlin.

[mduesterhoeft]

Just had a deeper look. The formats given [here ](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#dataTypeFormat) are not a feature of JsonSchema. It is a feature of openApi data types. Both are largely the same but openAPI data types extend JsonSchema.

Since we rely on json schema you suggestion can currently not be implemented. We would have to change to openApi data types entirely. For the openApi specifications this would be an improvement, but of course JsonSchema is more universal and could also be used in e.g. RAML.

[mgwoj]

I do not understand your statement from the last paragraph that we should stick to the pure JsonSchema. According to the description of the project on the main page https://github.com/ePages-de/restdocs-api-spec it supports:

• OpenAPI 2.0 in json and yaml
• OpenAPI 3.0.1 in json and yaml

Link for OpenAPI 3.0.1 points to the https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md specification, which states that data types can be tuned by specifying format. It means that format should be supported by your plugin.

[mduesterhoeft]

Please see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#schemaObject

This object is an extended subset of the JSON Schema Specification Wright Draft 00

So the spec describes that SchemaObject is JsonSchema with some extensions (like the format).

This project currently produces JsonSchema from the field descriptors and thus currently cannot add the OpenApi extenstions like format.

[mgwoj]

Please read the "Schema Object" section till the end. There is statement

The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.

• type - Value MUST be a string. Multiple types via an array are not supported. [...]
• format - See Data Type Formats for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.

So my understanding is that format should be supported. And it is used by i.e. ApiMatic when converting OpenApi contract to RAML.