OpenAPI Basics

"The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service."

See OpenAPI Initaitive for more information.

Runtime

Configuration

OpenAPI in Comflow will by defalt support any JAX-RS service defined in the sitedef.xml. To disable OpenApi for a service parameter 'enableOpenAPI':

    <Startup>
        <RestServices>
            <RestService path="test" classes="com.corzia.examples.jaxrs.TestRESTService" enableOpenAPI="false" runAsUser="comflow" networks="192.168.50.*"/>
        </RestServices>
    </Startup>

OpenAPI

The runtime OpenAPI definition will be accessable under */rs/<path>/openapi.json for Json and */rs/<path>/openapi.yaml for Yaml. E.g. http://localhost:8080/comflow/rs/util/openapi.yaml

OpenAPI UI

The runtime OpenAPI UI will be accessable under */rs/<path>/api-docs/?url=../openapi.json. E.g. http://localhost:8080/comflow/rs/util/api-docs/?url=../openapi.json

Development

Design First

To generate Java classes from OpenAPI / Swagger definitions see Swagger Codegen on Github.

Code First

You can describe the service by combining JAX-RS annotations and OpenAPI annotations.

package com.corzia.examples.jaxrs;

import java.util.List;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;

import io.swagger.model.Item;
import io.swagger.model.Items;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import net.comactivity.ws.rs.AbstractRestService;

@Path("/")
@OpenAPIDefinition(
        info = @Info(
                title = "Test API",
                description = "Use this API as an example."
                )
        )
public class TestRESTService extends AbstractRestService {

    @GET
    @Path("/getAllItems")
    @Produces({ MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
    @Operation(summary = "Get item data for multiple items", tags = { "Item Data" })
    @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Successful response"),
            @ApiResponse(responseCode = "404", description = "Not found response") })
    public Items getAllItems(
            @QueryParam("FromChangedDate") @Parameter(description = "Leave blank to retrieve all items or send a dateTime in format ´YYYY-MM-DD´.", required = false) String fromChangedDate) {
        
        Items items = new Items();
        List<Item> itemsList = findItems(fromChangedDate);
        if (!itemsList.isEmpty()) {
            items.setItems(itemsList);
        }
        return items;
    }
...
}