Blog from March, 2018

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

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.

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. 

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