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