Blog from July, 2018

There's a behavior change being made to the default value on @RestMethod(path).  If not specified, the value is now inferred from the Java method name.

This can result in cleaner-looking code.

The previous behavior was to default to the value "/*".

More information can be found here:

Documentation reorg

FYI....I've broken up the overview.html file into individual topics:  

The overview document was just getting too unwieldy (the Eclipse HTML editor struggled with it).  The smaller parts should be easier to work with, and reorganizing pages should now be much easier.  Also, broken links should now be fewer in number.

The DocGenerator class will take all the individual pages and combine them into the same overview.html page as before.

The generator is not currently part of the build process so it has to be executed manually to generate the overview.   

In 7.2, we're introducing auto-validation of Swagger annotations.  What this means is that the various Swagger annotations are not just used for populating the Swagger JSON / UI, but are actively used in serializing/parsing/validating the HTTP parts.

For example:

This example shows a parameter of type PetStatus[] (which happens to be enums, but could also be POJOs as well).  The type and collectionFormat attributes tell the framework to parse the incoming value as a comma-delimited list.  The _enum shows the possible valid values.  A BadRequest is thrown if any values don't match.  

Part of this change includes combining the client-side and server-side annotations into a single set of annotations (no more confusing org.apache.juneau.remoteable.Query with

Features include:

  • Support for all of Swagger 2.0.
  • Auto-validation for:
    • Numeric values (minimummaximumexclusiveMinimumexclusiveMaximummultipleOf).
    • String values (minLengthmaxLengthenum).
    • Collection values (itemsminItemsmaxItemsuniqueItems).
    • Object values (propertiesmaxPropertiesminPropertiesadditionalProperties).
    • Existence of values (requiredallowEmptyValue).
  • Support for both client-side and server-side annotations.
  • Works on the Body annotation as well.  If the media-type of the body does not match an existing serializer/parser, then the Swagger rules are used for marshalling.
  • UON notation is still supported, so you can still represent arbitrary POJOs as any of the HTTP parts.  However, you have to explicitly specify format="uon".

Juneau 7.2.0 is close to release but there is still a considerable amount of documentation to be written.  The Javadocs on the classes themselves should be mostly complete, but much remains to be written in the overview document.

I've uploaded a preview of the Javadocs so far here:

To help identify new and in-progress documentation, I've added temporary color coding to new and modified sections...

If there is any documentation lacking, now would be a good time to point it out (smile)