Programming with Java APIs, Part 1: OpenAPI and Swagger

Get started with API-driven development for cloud and microservices architectures

1 2 Page 2
Page 2 of 2

Notice that the "paths" entry contains a collection of URLs. These URLs specify the paths mapped by the API. Each URL contains a collection of HTTP methods like get, post, and so on, designating a specific endpoint. Each endpoint, then, is a coordinate of a path and method. These coordinates provide a wealth of information to describe your application endpoints. You can forego that information if you want (as shown in Listing 1) but it's available for cases where you need to specify your application in detail.

Now let's look closer at Listing 2.

The "/part-type" GET coordinate contains general information, like a description and an operationId. It also defines a "produces" entry, specifying what a consumer of this endpoint can expect in output.

The "parameters" entry describes the query parameters accepted by this endpoint.

"responses" contains a collection of HTTP response codes, designating the responses made explicit by the API spec for this endpoint. Here we have the "200" all-good response, and a "default" response. Both the "200" and "default" responses give a description and a "schema" definition.

The "schema" entry defines the expected return format. Knowing that the /part-type GET entry declares that it produces "application/json", you can expect that the schema will define a JSON structure.

Document references and JSON schema

The "type": "array" in Listing 2 tells you that this endpoint will return a JSON collection. The "items" type then says: "Here is what that collection looks like." Also note that inside "items" is a document reference.

OpenAPI and other API formats support document references. The "$ref" syntax indicates a reference to another place in the definition, and the "#" of the target indicates the document root. Therefore, both the "/part-type" GET 200 and the "/part-type" GET default elements reference the API's definitions element. This is a shortcut way of specifying their respective schemas, and it keeps these elements DRY.

Listing 3 shows a simple reference for the PartType snippet.

Listing 3. A simple OpenAPI schema

"definitions": {
    "PartType": {
        "type": "object",
            "required": [
            "properties": {
                "id": {
                    "type": "integer",
                    "format": "int64"
                "name": {
                    "type": "string"

Here you see how a simple JSON schema can be. What's more, this schema is reusable. You could even re-use it as a subsection of another schema. Like endpoint mappings, the schema definitions in OpenAPI can begin simply and expand to be very expressive.

Keeping Java APIs lean

The formalization of RESTful API definitions is somewhat controversial, with some strongly opposing the threat of bloat and overhead, which they fear encroaches on the practical, lean nature of REST. A consensus nevertheless seems to be coalescing around the use of formalized API specifications.

To be the most effective, Java API definitions must contribute their benefits with a minimum of overhead to coding and other activities. We want our Java APIs to complement and not complicate development. Otherwise we risk going back to the same complexity that undermined early versions of SOA and SaaS. While large organizations and projects can support more detailed API development, leaner projects are free to use just enough API to make sense. That, in a nutshell, is the beauty of programming with Java APIs.

Look for the second half of this article soon. We'll dig more into Swagger's capabilities, especially for assisting with coding.

1 2 Page 2
Page 2 of 2