OpenAPI Methodology

Unlike the other Juneau serializers and parsers that convert input and output directly to-and-from POJOs, the OpenAPI serializers and parsers use intermediate objects based on the type and format of the schema.

The following table shows the "natural" intermediate type of the object based on the type/format:

TypeFormatIntermediate Java Type
string or empty byte
binary
binary-spaced
byte[]
date
date-time
{@link java.util.Calendar}
uon No intermediate type.
(serialized directly to/from POJO)
empty {@link java.lang.String}
boolean empty {@link java.lang.Boolean}
integer int32 {@link java.lang.Integer}
int64 {@link java.lang.Long}
number float {@link java.lang.Float}
double {@link java.lang.Double}
array empty Arrays of intermediate types on this list.
uon No intermediate type.
(serialized directly to/from POJO)
object empty Map<String,Object>
uon No intermediate type.
(serialized directly to/from POJO)

The valid POJO types for serializing/parsing are based on the intermediate types above. As a general rule, any POJOs that are the intermediate type or transformable to or from the intermediate type are valid POJO types.

For example, the following POJO type can be transformed to and from a byte array.

// Sample POJO class convertable to and from a byte[]. public class MyPojo { // Constructor used by parser. public MyPojo(byte[] fromBytes) {...} // toX method used by serializer. public byte[] toBytes() {...} }

This example shows how that POJO can be converted to a BASE64-encoded string.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. HttpPartSchema schema = HttpPartSchema.create().type("string").format("byte").build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart = s.serialize(schema, myPojo); // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; myPojo = p.parse(schema, httpPart, MyPojo.class);

In addition to defining format, the schema also allows for validations of the serialized form.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. // Serialized string must be no smaller than 100 characters. HttpPartSchema schema = HttpPartSchema.create().type("string").format("byte").minLength(100).build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart; try { httpPart = s.serialize(schema, myPojo); } catch (SchemaValidationException e) { // Oops, output too small. } // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; try { myPojo = p.parse(schema, httpPart, MyPojo.class); } catch (SchemaValidationException e) { // Oops, input too small. }

It looks simple, but the implementation is highly sophisticated being able to serialize and parse and validate using complex schemas.

The next sections go more into depth on serializing and parsing various POJO types.