Examples with RestParameter org.opencastproject.util.doc.rest.RestParameter used on opensource projects

Example 1 with RestParameter

use of org.opencastproject.util.doc.rest.RestParameter in project opencast by opencast.

the class RestDocsAnnotationTest method testRestQueryDocs2.

/**
 * This tests the functionality of @RestQuery, @RestParameter, @RestResponse, @Path, @Produces, @Consumes annotation
 * type using a different technique.
 */
@Test
public void testRestQueryDocs2() {
    Method testMethod;
    try {
        testMethod = TestServletSample.class.getMethod("methodA");
        if (testMethod != null) {
            RestDocData restDocData = new RestDocData("NAME", "TITLE", "URL", null, new TestServletSample(), new HashMap<String, String>());
            RestQuery restQueryAnnotation = (RestQuery) testMethod.getAnnotation(RestQuery.class);
            Path pathAnnotation = (Path) testMethod.getAnnotation(Path.class);
            Produces producesAnnotation = (Produces) testMethod.getAnnotation(Produces.class);
            String httpMethodString = null;
            // we cannot hard code the GET.class or POST.class because we don't know which one is used.
            for (Annotation a : testMethod.getAnnotations()) {
                HttpMethod method = (HttpMethod) a.annotationType().getAnnotation(HttpMethod.class);
                if (method != null) {
                    httpMethodString = method.value();
                }
            }
            RestEndpointData endpoint = new RestEndpointData(testMethod.getReturnType(), restDocData.processMacro(restQueryAnnotation.name()), httpMethodString, "/" + pathAnnotation.value(), restDocData.processMacro(restQueryAnnotation.description()));
            if (!restQueryAnnotation.returnDescription().isEmpty()) {
                endpoint.addNote("Return value description: " + restDocData.processMacro(restQueryAnnotation.returnDescription()));
            }
            // name, description and return description
            assertEquals("addTrackInputStream", endpoint.getName());
            assertEquals("Add a media track to a given media package using an input stream", endpoint.getDescription());
            assertEquals(1, endpoint.getNotes().size());
            assertEquals("Return value description: augmented media package", endpoint.getNotes().get(0));
            // HTTP method
            assertEquals("POST", endpoint.getMethod());
            assertEquals("/addTrack", endpoint.getPath());
            // @Produces
            if (producesAnnotation != null) {
                for (String format : producesAnnotation.value()) {
                    endpoint.addFormat(new RestFormatData(format));
                }
            }
            assertEquals(1, endpoint.getFormats().size());
            assertEquals(MediaType.TEXT_XML, endpoint.getFormats().get(0).getName());
            // responses
            for (RestResponse restResp : restQueryAnnotation.reponses()) {
                endpoint.addStatus(restResp, restDocData);
            }
            assertEquals(3, endpoint.getStatuses().size());
            assertEquals(HttpServletResponse.SC_OK, endpoint.getStatuses().get(0).getCode());
            assertEquals("Returns augmented media package", endpoint.getStatuses().get(0).getDescription());
            assertEquals(HttpServletResponse.SC_BAD_REQUEST, endpoint.getStatuses().get(1).getCode());
            assertEquals(null, endpoint.getStatuses().get(1).getDescription());
            assertEquals(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, endpoint.getStatuses().get(2).getCode());
            assertEquals(null, endpoint.getStatuses().get(2).getDescription());
            // body parameter
            if (restQueryAnnotation.bodyParameter().type() != RestParameter.Type.NO_PARAMETER) {
                endpoint.addBodyParam(restQueryAnnotation.bodyParameter(), restDocData);
            }
            assertEquals("BODY", endpoint.getBodyParam().getName());
            assertEquals("The media track file", endpoint.getBodyParam().getDescription());
            assertTrue(endpoint.getBodyParam().isRequired());
            assertEquals(null, endpoint.getBodyParam().getDefaultValue());
            assertTrue("FILE".equalsIgnoreCase(endpoint.getBodyParam().getType()));
            // path parameter
            for (RestParameter restParam : restQueryAnnotation.pathParameters()) {
                endpoint.addPathParam(new RestParamData(restParam, restDocData));
            }
            assertEquals(1, endpoint.getPathParams().size());
            assertEquals("wdID", endpoint.getPathParams().get(0).getName());
            assertEquals("Workflow definition id", endpoint.getPathParams().get(0).getDescription());
            assertTrue(endpoint.getPathParams().get(0).isRequired());
            assertTrue(endpoint.getPathParams().get(0).isPath());
            assertEquals(null, endpoint.getPathParams().get(0).getDefaultValue());
            assertTrue("STRING".equalsIgnoreCase(endpoint.getPathParams().get(0).getType()));
            // query parameters
            for (RestParameter restParam : restQueryAnnotation.restParameters()) {
                if (restParam.isRequired()) {
                    endpoint.addRequiredParam(new RestParamData(restParam, restDocData));
                } else {
                    endpoint.addOptionalParam(new RestParamData(restParam, restDocData));
                }
            }
            // #1
            assertEquals(1, endpoint.getRequiredParams().size());
            assertEquals("flavor", endpoint.getRequiredParams().get(0).getName());
            assertEquals("The kind of media track", endpoint.getRequiredParams().get(0).getDescription());
            assertTrue(endpoint.getRequiredParams().get(0).isRequired());
            assertEquals("Default", endpoint.getRequiredParams().get(0).getDefaultValue());
            assertTrue("STRING".equalsIgnoreCase(endpoint.getRequiredParams().get(0).getType()));
            // #2
            assertEquals(1, endpoint.getOptionalParams().size());
            assertEquals("mediaPackage", endpoint.getOptionalParams().get(0).getName());
            assertEquals("The media package as XML", endpoint.getOptionalParams().get(0).getDescription());
            assertFalse(endpoint.getOptionalParams().get(0).isRequired());
            assertEquals(null, endpoint.getOptionalParams().get(0).getDefaultValue());
            assertTrue("TEXT".equalsIgnoreCase(endpoint.getOptionalParams().get(0).getType()));
        }
    } catch (SecurityException e) {
        fail();
    } catch (NoSuchMethodException e) {
        fail();
    }
}

Example 2 with RestParameter

use of org.opencastproject.util.doc.rest.RestParameter in project opencast by opencast.

the class RestDocData method addEndpoint.

/**
 * Add an endpoint to the Rest documentation.
 *
 * @param restQuery
 *          the RestQuery annotation type storing information of an endpoint
 * @param returnType
 *          the return type for this endpoint. If this is {@link javax.xml.bind.annotation.XmlRootElement} or
 *          {@link javax.xml.bind.annotation.XmlRootElement}, the XML schema for the class will be made available to
 *          clients
 * @param produces
 *          the return type(s) of this endpoint, values should be constants from <a
 *          href="http://jackson.codehaus.org/javadoc/jax-rs/1.0/javax/ws/rs/core/MediaType.html"
 *          >javax.ws.rs.core.MediaType</a> or ExtendedMediaType
 *          (org.opencastproject.util.doc.rest.ExtendedMediaType).
 * @param httpMethodString
 *          the HTTP method of this endpoint (e.g. GET, POST)
 * @param path
 *          the path of this endpoint
 */
public void addEndpoint(RestQuery restQuery, Class<?> returnType, Produces produces, String httpMethodString, Path path) {
    String pathValue = path.value().startsWith("/") ? path.value() : "/" + path.value();
    RestEndpointData endpoint = new RestEndpointData(returnType, this.processMacro(restQuery.name()), httpMethodString, pathValue, processMacro(restQuery.description()));
    // Add return description if needed
    if (!restQuery.returnDescription().isEmpty()) {
        endpoint.addNote("Return value description: " + processMacro(restQuery.returnDescription()));
    }
    // Add formats
    if (produces != null) {
        for (String format : produces.value()) {
            endpoint.addFormat(new RestFormatData(format));
        }
    }
    // Add responses
    for (RestResponse restResp : restQuery.reponses()) {
        endpoint.addStatus(restResp, this);
    }
    // Add body parameter
    if (restQuery.bodyParameter().type() != RestParameter.Type.NO_PARAMETER) {
        endpoint.addBodyParam(restQuery.bodyParameter(), this);
    }
    // Add path parameter
    for (RestParameter pathParam : restQuery.pathParameters()) {
        endpoint.addPathParam(new RestParamData(pathParam, this));
    }
    // Add query parameter (required and optional)
    for (RestParameter restParam : restQuery.restParameters()) {
        if (restParam.isRequired()) {
            endpoint.addRequiredParam(new RestParamData(restParam, this));
        } else {
            endpoint.addOptionalParam(new RestParamData(restParam, this));
        }
    }
    // Set the test form after all parameters are added.
    endpoint.setTestForm(new RestFormData(endpoint));
    // Add the endpoint to the corresponding group based on its HTTP method
    if ("GET".equalsIgnoreCase(httpMethodString) || "HEAD".equalsIgnoreCase(httpMethodString)) {
        addEndpoint(READ_ENDPOINT_HOLDER_NAME, endpoint);
    } else if ("DELETE".equalsIgnoreCase(httpMethodString) || "POST".equalsIgnoreCase(httpMethodString) || "PUT".equalsIgnoreCase(httpMethodString)) {
        addEndpoint(WRITE_ENDPOINT_HOLDER_NAME, endpoint);
    }
}