Documenting RESTful APIs

 12package io.openliberty.guides.inventory;
 13
 14import java.util.Properties;
 15import jakarta.enterprise.context.RequestScoped;
 16import jakarta.inject.Inject;
 17import jakarta.ws.rs.GET;
 18import jakarta.ws.rs.Path;
 19import jakarta.ws.rs.PathParam;
 20import jakarta.ws.rs.Produces;
 21import jakarta.ws.rs.core.MediaType;
 22import jakarta.ws.rs.core.Response;
 23
 24import org.eclipse.microprofile.openapi.annotations.Operation;
 25import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
 26import org.eclipse.microprofile.openapi.annotations.media.Content;
 27import org.eclipse.microprofile.openapi.annotations.media.Schema;
 28import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 29import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 30import org.eclipse.microprofile.openapi.annotations.responses.APIResponseSchema;
 31import io.openliberty.guides.inventory.model.InventoryList;
 32
 33@RequestScoped
 34@Path("/systems")
 35public class InventoryResource {
 36
 37    @Inject
 38    InventoryManager manager;
 39
 40    @GET
 41    @Path("/{hostname}")
 42    @Produces(MediaType.APPLICATION_JSON)
 45    @APIResponse(
 46        responseCode = "404",
 47        description = "Missing description",
 48        content = @Content(mediaType = "application/json"))
 51    @APIResponseSchema(value = Properties.class,
 52        responseDescription = "JVM system properties of a particular host.",
 53        responseCode = "200")
 56    @Operation(
 57        summary = "Get JVM system properties for particular host",
 58        description = "Retrieves and returns the JVM system properties from the system "
 59        + "service running on the particular host.")
 62    public Response getPropertiesForHost(
 64        @Parameter(
 65            description = "The host for whom to retrieve "
 66                + "the JVM system properties for.",
 67            required = true,
 68            example = "localhost",
 69            schema = @Schema(type = SchemaType.STRING))
 71        @PathParam("hostname") String hostname) {
 72        // Get properties for host
 73        Properties props = manager.get(hostname);
 74        if (props == null) {
 75            return Response.status(Response.Status.NOT_FOUND)
 76                           .entity("{ \"error\" : "
 77                                   + "\"Unknown hostname " + hostname
 78                                   + " or the resource may not be "
 79                                   + "running on the host machine\" }")
 80                           .build();
 81        }
 82
 83        //Add to inventory to host
 84        manager.add(hostname, props);
 85        return Response.ok(props).build();
 86    }
 87
 88    @GET
 89    @Produces(MediaType.APPLICATION_JSON)
 91    @APIResponseSchema(value = InventoryList.class,
 92        responseDescription = "host:properties pairs stored in the inventory.",
 93        responseCode = "200")
 94    @Operation(
 95        summary = "List inventory contents.",
 96        description = "Returns the currently stored host:properties pairs in the "
 97        + "inventory.")
 99    public InventoryList listContents() {
100        return manager.list();
101    }
102
103}104

12package io.openliberty.guides.inventory.model;
13
14import java.util.List;
15import org.eclipse.microprofile.openapi.annotations.media.Schema;
16
18@Schema(name = "InventoryList",
19description = "POJO that represents the inventory contents.")
22public class InventoryList {
23
25    @Schema(required = true)
27    private List<SystemData> systems;
28
29    public InventoryList(List<SystemData> systems) {
30        this.systems = systems;
31    }
32
33    public List<SystemData> getSystems() {
34        return systems;
35    }
36
37    public int getTotal() {
38        return systems.size();
39    }
40}
42

12package io.openliberty.guides.inventory.model;
13
14import java.util.Properties;
15import org.eclipse.microprofile.openapi.annotations.media.Schema;
16
18@Schema(name = "SystemData",
19       description = "POJO that represents a single inventory entry.")
21public class SystemData {
22
24    @Schema(required = true)
26    private final String hostname;
27
29    @Schema(required = true)
31    private final Properties properties;
32
33    public SystemData(String hostname, Properties properties) {
34        this.hostname = hostname;
35        this.properties = properties;
36    }
37
38    public String getHostname() {
39        return hostname;
40    }
41
42    public Properties getProperties() {
43        return properties;
44    }
45
46    @Override
47    public boolean equals(Object host) {
48        if (host instanceof SystemData) {
49            return hostname.equals(((SystemData) host).getHostname());
50        }
51        return false;
52    }
53}54

12package io.openliberty.guides.inventory.filter;
13
14import java.util.Arrays;
15import java.util.Collections;
16
17import org.eclipse.microprofile.openapi.OASFactory;
18import org.eclipse.microprofile.openapi.OASFilter;
19import org.eclipse.microprofile.openapi.models.OpenAPI;
20import org.eclipse.microprofile.openapi.models.info.License;
21import org.eclipse.microprofile.openapi.models.info.Info;
22import org.eclipse.microprofile.openapi.models.responses.APIResponse;
23import org.eclipse.microprofile.openapi.models.servers.Server;
24import org.eclipse.microprofile.openapi.models.servers.ServerVariable;
25
26public class InventoryOASFilter implements OASFilter {
27
28  @Override
30  public APIResponse filterAPIResponse(APIResponse apiResponse) {
31    if ("Missing description".equals(apiResponse.getDescription())) {
32      apiResponse.setDescription("Invalid hostname or the system service may not "
33          + "be running on the particular host.");
34    }
35    return apiResponse;
36  }
38
39  @Override
42  public void filterOpenAPI(OpenAPI openAPI) {
45    openAPI.setInfo(
46        OASFactory.createObject(Info.class).title("Inventory App").version("1.0")
47                  .description(
48                      "App for storing JVM system properties of various hosts.")
49                  .license(
50                      OASFactory.createObject(License.class)
51                                .name("Eclipse Public License - v 2.0").url(
52                                    "https://www.eclipse.org/legal/epl-2.0")));
53
54    openAPI.addServer(
55        OASFactory.createServer()
56                  .url("http://localhost:{port}")
57                  .description("Simple Open Liberty.")
58                  .variables(Collections.singletonMap("port",
59                                 OASFactory.createServerVariable()
60                                           .defaultValue("9080")
61                                           .description("Server HTTP port."))));
63  }
65
66}67