Allow descriptors to be loaded from a file

[kakawait]

Overview

Starting discussion on Gitter

Would be great to be able to externalize documentation message outside of testing class like .properties or .yml files.

Moreover external resources could be localized to allow publish documentation in multiple language:

message.properties
message_fr_FR.properties
message_zh_CN.properties
...

Furthermore link between external resources and testing parameters should be automatic. We must use convention filename/path convention to be able to link each together.

Details

There are many points to take care:

• Which external resources format will be supported? (properties, yml)
• How to avoid collisions?
• An external resource per document identifier?
• Flat file and prefix (document identifier)?
• How can I manage placeholder?

key = blabla blabla forbidden values are {0}

• How to describe message type: STRING or whatever
• Ability to load external resource outside of Classpath

[wilkinsona]

I think localization should be considered as a separate issue for a couple of reasons:

• There's benefit to implementing this without support for localization
• Localization also affects things like the default snippet templates which currently hardcode English table column names

[marceloverdijk]

I think we should offer something like:

field1: The description of field 1
field2:
  type: STRING
  description: The description of field 2
  attributes:
    - key: constraints
      value: Not null
    - key: remarks
      value: Lorem ipsem

As the example points out (field1) there should be a quick shorthand notation available but for situations needed it should be possible to define the complete set of type, description and attributes list.

Personally I would strongly favour yaml but think that ordinary .properties should also be supported.

Regarding one big file or separate properties file per method I'm not sure.
For not to big projects I think I would like a single file, for large project I don't know yet.

Another interesting aspect about this when documenting fields like this, is how we can reuse parts.
When using yaml we could use ? and *; for ordinary .property files I don't know.

[kakawait]

@marceloverdijk do you have any sample idea to represent what you posted above in properties format?

[marceloverdijk]

@kakawait something like this?

field1=The description of field 1
field2.type=STRING
field2.description=The description of field 2
field2.attributes1.key=constraints
field2.attributes1.value=Not Null
field2.attributes2.key=remarks
field2.attributes2.value=Lorem ipsem

or alternatively something like field2.attributes[1].key=

I don't like it but that's why I think yaml would be much better suited (in general).

[wilkinsona]

Ignoring the shorthand for only specifying a description for the moment, I think the YAML could be improved:

field1:
  description: The description of field 1
field2:
  type: String
  description: The description of field 2
  attributes:
    constraints: Not null
    remarks: Lorem ipsem

The equivalent properties would be:

field1.description = The description of field 1
field2.type = String
field2.description = The description of field 2
field2.attributes.constraints = Not null
field2.attributes.remarks = Lorem ipsem

[patrice-conil]

As we also use swagger, i've made a maven plugin that generate FieldDescriptors from model classes.
You should find this here: restdoc-helper