Blog

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:

http://juneau.apache.org/site/apidocs_preview/overview-summary.html#juneau-rest-server.RestMethod

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 org.apache.juneau.rest.annotation.Query).

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:
http://juneau.apache.org/site/apidocs_preview/index.html

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)

In 7.2.0, I'm adding support for POJO REST requests that don't include Accept and Media-Type headers.

Previously, if your requests did not contain Accept or Content-Type headers, you had to use Readers and Writers to work with the HTTP request and response bodies.  Otherwise you would get Not Acceptable (406) and Unsupported Media Type (415) response codes.  

This behavior is now being relaxed.  If your request does not contain media-type headers, then you can still used POJOs for requests and responses.

For example, this is a snippet from the Javadoc on the Body annotation describing the types of objects you can use in REST Java methods to represent the body of the request:

JUnit Test Results

FYI....JUnit testcase results have been added to the Jenkins builds...

I'm adding the following classes to the juneau-rest-server module to allow you to unit test your REST resources without the need of running them in a servlet container:

Here's an example of it in use...

Instead of routing requests through a servlet container, it simply creates the RestContext object for the resource and calls the RestContext.getCallHandler().service(request, response); method with mocked-up ServletRequest and ServletResponse objects.

Here's what it looks like in expanded form:

In theory, everything should work identically to how it would behave in a servlet container, only faster and more efficient.

The MockRest object can also be used with the RestClient class to perform serverless client-side testing against REST resource classes:

This last feature is useful if you want to perform serverless unit testing of REST proxy interfaces.

 

 

Configurable look-and-feel

This change is being introduced in 7.1.1 to resolve the following feature request:

https://issues.apache.org/jira/projects/JUNEAU/issues/JUNEAU-82

 

The change introduces an external folder in the JVM working directory containing images and stylesheets used by the microservice:

The REST configuration section can be used to tailor the header and footer on the pages:

The BasicRestConfig interface (which defines the default settings for BasicRestServlet) is now defined as:

Note that the theme files are externally accessible and can be modified to produce any look-and-feel you desire.

The microservice still works without the files directory.  An embedded devops.css is included in the jar as a default spreadsheet.

If you're testing out changes in the theme stylesheets, you may want to set the following system property that prevents caching of those files so that you don't need to restart the microservice each time a change is made:

 

Quick update on the Swagger UI enhancements.

The design allows you to pull in Swagger from any of the following sources (or any combination):

  • Localized Swagger JSON files on the classpath.
  • Swagger defined on class-level and method-level annotations.
  • Swagger fragments defined in resource bundles.
  • Auto-detection if not found above (paths, methods, schemas, etc...).

The general idea is you can let Juneau auto-generate the Swagger documentation, or provide your own Swagger JSON, or do a combination of auto and manual.

 

Here's the Petstore app OPTIONS page based on the Swagger.io Petstore example...

 

Operations are expandable and gives you information about the schema.  

In this case, the schema information was auto-detected and generated using the JsonSchemaSerializer. 

 

Examples for all the supported types are provided via a select when an @Example-annotated method exists on the POJO class (or otherwise defined in the Swagger JSON).

 

For example, RDF....

 

 

 

Swagger UI enhancements

A quick update on the work I've been doing around Swagger enhancements.  There's still much work to do, but I wanted to provide a sneak-peek.

As previously requested, it would be nice to have more user-friendly OPTIONS pages based on Swagger UI. 

Here's an example of what it looks like so far...

It's implemented as a per-media-type PojoSwap<Swagger,Div> that replaces a Swagger object with HTML5 beans when rendered as HTML.

 

The examples can be embedded in the Swagger JSON or annotations. They can also come from the beans themselves via a new @Example annotation that can be applied to static methods on a bean:

public class Pet {

	@Example
	public static Pet example() {
		// return an example of this object.
	}
}

These examples beans are then serialized to all the supported languages and inserted into the generated Swagger.

 

Here's what it looks like in the light and dark themes...

 

 

There are also general improvements coming to the Swagger API itself such as better support for definitions and references, and other fixes for pain-points I'm discovering along the way.

 

Documentation Updates

I think I'm finally finished cleaning up the documentation.  I've been working at it since December and it's been quite time consuming, but I'm pretty happy with the results:

http://juneau.apache.org/index.html#documentation.html

There's a LOT of documentation to go through, but anyone willing to get into the depths of Juneau and do some proofreading?  You might even find some interesting features you never knew existed. (smile)

Configuration API changes

We've made some significant changes to the Configuration API in 7.1.0.

Feature include:

  • Support for pluggable storage.
  • File-system watcher integration support.
  • New builder-based design.

The documentation has been rewritten for the juneau-config module and can be found here:

http://juneau.apache.org/site/apidocs/overview-summary.html#juneau-config

Homepage header image vote

Anyone have any preferences on changing the page header on our web page?

All but the first one are pulled from pexels.com.

1.

2.

3.

4.

5.

6.

7.

8.

9.

10

 

One last one that I kind of like....

 

FYI....the topics in the Javadoc overview document are now collapsable with zoom-in/out hover pointers:

(Technically they were always collapsable, but it wasn't obvious that you could do so without the mouse pointer)

Javadoc Link Tester

FYI....I just added a utility for finding broken links in the generated Javadocs.  I found hundreds of them.

It's just a simple class called JavadocLinkTester.  Just run it without args after running mvn javadoc:aggregate and it will find any broken links..

 

I recommend using it if you make any extensive updates to the Javadocs.

I looked for existing tools online but came up empty.  I also tried using the W3C link checker utility, but it was REALLY slow since it actually crawled all the links.

It would be nice to include this as part of the Maven build but I'm not familiar with creating Maven components.  

Source can be found here:

https://github.com/apache/juneau/blob/master/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/utils/JavadocLinkTester.java