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

May 24 '16 12:05 kakawait

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

May 24 '16 13:05 wilkinsona

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.

May 24 '16 19:05 marceloverdijk

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

May 25 '16 08:05 kakawait

@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).

May 25 '16 09:05 marceloverdijk

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

May 25 '16 13:05 wilkinsona

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

Oct 21 '16 11:10 patrice-conil

Allow descriptors to be loaded from a file

Overview

Details