org.eclipse.microprofile.openapi.models.parameters.Parameter Java Examples

/**
 * Reads a map of Parameter annotations.
 * 
 * @param context the scanning context
 * @param annotationValue Map of {@literal @}Parameter annotations
 * @return List of Parameter model
 */
public static Optional<List<Parameter>> readParametersList(final AnnotationScannerContext context,
        final AnnotationValue annotationValue) {
    if (annotationValue != null) {
        IoLogging.log.annotationsList("@Parameter");
        List<Parameter> parameters = new ArrayList<>();
        AnnotationInstance[] nestedArray = annotationValue.asNestedArray();
        for (AnnotationInstance nested : nestedArray) {
            Parameter parameter = readParameter(context, nested);
            if (parameter != null) {
                parameters.add(parameter);
            }
        }
        return Optional.of(parameters);
    }
    return Optional.empty();
}
 

/**
 * Returns the list of {@link Schema}s defined for the given {@link Parameter}.
 * A schema can be defined either via the parameter's "schema" property, or any
 * "content.*.schema" property.
 *
 * @param parameter Parameter
 * @return list of schemas, never null
 */
public static List<Schema> getParameterSchemas(Parameter parameter) {
    if (parameter.getSchema() != null) {
        return Arrays.asList(parameter.getSchema());
    }
    Map<String, MediaType> mediaTypes = getMediaTypesOrEmpty(parameter.getContent());
    if (!mediaTypes.isEmpty()) {
        List<Schema> schemas = new ArrayList<>(mediaTypes.size());

        for (MediaType mediaType : mediaTypes.values()) {
            if (mediaType.getSchema() != null) {
                schemas.add(mediaType.getSchema());
            }
        }
    }
    return Collections.emptyList();
}
 

@Test
public void parameterTest() {
    final Parameter p = processConstructible(Parameter.class);
    
    final String exampleKey = "myExample";
    final Example exampleValue = createConstructibleInstance(Example.class);
    checkSameObject(p, p.addExample(exampleKey, exampleValue));
    checkMapEntry(p.getExamples(), exampleKey, exampleValue);
    assertEquals(p.getExamples().size(), 1, "The map is expected to contain one entry.");
    p.removeExample(exampleKey);
    assertEquals(p.getExamples().size(), 0, "The map is expected to be empty.");
    
    final String exampleKey2 = "myExampleKey2";
    final Example exampleValue2 = createConstructibleInstance(Example.class);
    p.setExamples(Collections.singletonMap(exampleKey2, exampleValue2));
    checkMapEntry(p.getExamples(), exampleKey2, exampleValue2);
    assertEquals(p.getExamples().size(), 1, "The map is expected to contain one entry.");
    checkSameObject(p, p.addExample(exampleKey, exampleValue));
    checkMapEntry(p.getExamples(), exampleKey, exampleValue);
    assertEquals(p.getExamples().size(), 2, "The map is expected to contain two entries.");
    
    Example otherExampleValue = createConstructibleInstance(Example.class);
    checkMapImmutable(p, Parameter::getExamples, "otherExample", otherExampleValue);
    checkNullValueInAdd(p::getExamples, p::addExample, "otherExample", exampleValue);
}
 

/**
 * Reads a map of Parameter annotations.
 * 
 * @param context the scanning context
 * @param annotationValue Map of {@literal @}Parameter annotations
 * @return Map of Parameter model
 */
public static Map<String, Parameter> readParameters(final AnnotationScannerContext context,
        final AnnotationValue annotationValue) {
    if (annotationValue == null) {
        return null;
    }
    IoLogging.log.annotationsMap("@Parameter");
    Map<String, Parameter> parameters = new LinkedHashMap<>();
    AnnotationInstance[] nestedArray = annotationValue.asNestedArray();
    for (AnnotationInstance nested : nestedArray) {
        String name = JandexUtil.stringValue(nested, Parameterizable.PROP_NAME);
        if (name == null && JandexUtil.isRef(nested)) {
            name = JandexUtil.nameFromRef(nested);
        }
        if (name != null) {
            Parameter parameter = readParameter(context, nested);
            if (parameter != null) {
                parameters.put(name, parameter);
            }
        }
    }
    return parameters;
}
 

/**
 * Retrieves either the provided parameter {@link Parameter.Style}, the default
 * style of the parameter based on the <code>in</code> attribute, or null if <code>in</code> is not defined.
 * 
 * @param param the {@link Parameter}
 * @return the param's style, the default style defined based on <code>in</code>, or null if <code>in</code> is not defined.
 */
Style styleOf(Parameter param) {
    if (param.getStyle() != null) {
        return param.getStyle();
    }

    if (param.getIn() != null) {
        switch (param.getIn()) {
            case COOKIE:
            case QUERY:
                return Style.FORM;
            case HEADER:
            case PATH:
                return Style.SIMPLE;
            default:
                break;
        }
    }

    return null;
}
 

/**
 * Writes a {@link Parameter} into the JSON node.
 * 
 * @param node
 * @param model
 */
private static void writeParameter(ObjectNode node, Parameter model) {
    if (StringUtil.isNotEmpty(model.getRef())) {
        JsonUtil.stringProperty(node, Referenceable.PROP_$REF, model.getRef());
    } else {
        JsonUtil.stringProperty(node, Parameterizable.PROP_NAME, model.getName());
        JsonUtil.enumProperty(node, ParameterConstant.PROP_IN, model.getIn());
        JsonUtil.stringProperty(node, Parameterizable.PROP_DESCRIPTION, model.getDescription());
        JsonUtil.booleanProperty(node, Parameterizable.PROP_REQUIRED, model.getRequired());
        SchemaWriter.writeSchema(node, model.getSchema(), Parameterizable.PROP_SCHEMA);
        JsonUtil.booleanProperty(node, Parameterizable.PROP_ALLOW_EMPTY_VALUE, model.getAllowEmptyValue());
        JsonUtil.booleanProperty(node, Parameterizable.PROP_DEPRECATED, model.getDeprecated());
        JsonUtil.enumProperty(node, Parameterizable.PROP_STYLE, model.getStyle());
        JsonUtil.booleanProperty(node, Parameterizable.PROP_EXPLODE, model.getExplode());
        JsonUtil.booleanProperty(node, ParameterConstant.PROP_ALLOW_RESERVED, model.getAllowReserved());
        ObjectWriter.writeObject(node, Parameterizable.PROP_EXAMPLE, model.getExample());
        ExampleWriter.writeExamples(node, model.getExamples());
        ContentWriter.writeContent(node, model.getContent());
        ExtensionWriter.writeExtensions(node, model);
    }
}
 

/**
 * Processing a single JAX-RS resource class (annotated with @Path).
 * 
 * @param openApi
 * @param resourceClass
 * @param locatorPathParameters
 */
private void processResourceClass(final AnnotationScannerContext context,
        OpenAPI openApi,
        ClassInfo resourceClass,
        List<Parameter> locatorPathParameters) {
    JaxRsLogging.log.processingClass(resourceClass.simpleName());

    // Process @SecurityScheme annotations.
    processSecuritySchemeAnnotation(resourceClass, openApi);

    // Process Java security
    processJavaSecurity(resourceClass, openApi);

    // Now find and process the operation methods
    processResourceMethods(context, resourceClass, openApi, locatorPathParameters);
}
 

/**
 * Filters the given models.
 * 
 * @param filter
 * @param models
 */
private static List<Parameter> filterParameterList(OASFilter filter, List<Parameter> models) {
    if (models != null) {
        models = new ArrayList<>(models);
        ListIterator<Parameter> iterator = models.listIterator();
        while (iterator.hasNext()) {
            Parameter model = iterator.next();
            filterParameter(filter, model);

            if (filter.filterParameter(model) == null) {
                iterator.remove();
            }
        }
    }
    return models;
}
 

/**
 * Retrieves either the provided parameter {@link Parameter.Style}, the default
 * style of the parameter based on the <code>in</code> attribute, or null if <code>in</code> is not defined.
 * 
 * @param param the {@link Parameter}
 * @return the param's style, the default style defined based on <code>in</code>, or null if <code>in</code> is not defined.
 */
Style styleOf(Parameter param) {
    if (param.getStyle() != null) {
        return param.getStyle();
    }

    if (param.getIn() != null) {
        switch (param.getIn()) {
            case COOKIE:
            case QUERY:
                return Style.FORM;
            case HEADER:
            case PATH:
                return Style.SIMPLE;
            default:
                break;
        }
    }

    return null;
}
 

/**
 * Reads a {@link Parameter} OpenAPI node.
 * 
 * @param node the json object
 * @return Parameter model
 */
public static Parameter readParameter(final JsonNode node) {
    if (node == null || !node.isObject()) {
        return null;
    }
    IoLogging.log.singleJsonObject("Parameter");
    Parameter parameter = new ParameterImpl();

    parameter.setName(JsonUtil.stringProperty(node, Parameterizable.PROP_NAME));
    parameter.setIn(readParameterIn(node.get(ParameterConstant.PROP_IN)));
    parameter.setDescription(JsonUtil.stringProperty(node, Parameterizable.PROP_DESCRIPTION));
    parameter.setRequired(JsonUtil.booleanProperty(node, Parameterizable.PROP_REQUIRED).orElse(null));
    parameter.setDeprecated(JsonUtil.booleanProperty(node, Parameterizable.PROP_DEPRECATED).orElse(null));
    parameter.setAllowEmptyValue(JsonUtil.booleanProperty(node, Parameterizable.PROP_ALLOW_EMPTY_VALUE).orElse(null));
    parameter.setStyle(readParameterStyle(node.get(Parameterizable.PROP_STYLE)));
    parameter.setExplode(JsonUtil.booleanProperty(node, Parameterizable.PROP_EXPLODE).orElse(null));
    parameter.setAllowReserved(JsonUtil.booleanProperty(node, ParameterConstant.PROP_ALLOW_RESERVED).orElse(null));
    parameter.setSchema(SchemaReader.readSchema(node.get(Parameterizable.PROP_SCHEMA)));
    parameter.setContent(ContentReader.readContent(node.get(Parameterizable.PROP_CONTENT)));
    parameter.setExamples(ExampleReader.readExamples(node.get(Parameterizable.PROP_EXAMPLES)));
    parameter.setExample(readObject(node.get(Parameterizable.PROP_EXAMPLE)));
    parameter.setRef(JsonUtil.stringProperty(node, Referenceable.PROP_$REF));
    ExtensionReader.readExtensions(node, parameter);

    return parameter;
}
 

/**
 * Merge two lists of Parameters. Parameters are a special case because they must be unique
 * by the name in 'in' each have
 * 
 * @param values1
 * @param values2
 */
private static List<Parameter> mergeParameterLists(List<Parameter> values1, List<Parameter> values2) {
    values1 = new ArrayList<>(values1);

    for (Parameter value2 : values2) {
        Parameter match = null;
        for (Parameter value1 : values1) {
            if (value1.getName() == null || !value1.getName().equals(value2.getName())) {
                continue;
            }
            if (value1.getIn() == null || !value1.getIn().equals(value2.getIn())) {
                continue;
            }

            match = value1;
            break;
        }
        if (match == null) {
            values1.add(value2);
        } else {
            mergeObjects(match, value2);
        }
    }
    return values1;
}
 

/**
 * Filters the given models.
 * 
 * @param filter
 * @param models
 */
private static void filterParameters(OASFilter filter, Map<String, Parameter> models) {
    if (models != null) {
        Collection<String> keys = new ArrayList<>(models.keySet());
        for (String key : keys) {
            Parameter model = models.get(key);
            filterParameter(filter, model);

            if (filter.filterParameter(model) == null) {
                models.remove(key);
            }
        }
    }
}
 

private ParameterProcessor(AnnotationScannerContext scannerContext,
        Function<AnnotationInstance, Parameter> reader,
        List<AnnotationScannerExtension> extensions) {
    this.scannerContext = scannerContext;
    this.index = scannerContext.getIndex();
    this.readerFunction = reader;
    this.extensions = extensions;
}
 

/**
 * Merges two Lists. Any values missing from List1 but present in List2 will be added. Depending on
 * the type of list, further processing and de-duping may be required.
 * 
 * @param values1
 * @param values2
 */
@SuppressWarnings({ "rawtypes", "unchecked" })
private static Optional<List> mergeLists(List values1, List values2) {
    if (values1 == null && values2 == null) {
        return Optional.empty();
    }
    if (values1 != null && values2 == null) {
        return Optional.of(values1);
    }
    if (values1 == null && values2 != null) {
        return Optional.of(values2);
    }

    if (values1.get(0) instanceof String) {
        return Optional.of(mergeStringLists(values1, values2));
    }

    if (values1.get(0) instanceof Tag) {
        return Optional.of(mergeTagLists(values1, values2));
    }

    if (values1.get(0) instanceof Server) {
        return Optional.of(mergeServerLists(values1, values2));
    }

    if (values1.get(0) instanceof SecurityRequirement) {
        return Optional.of(mergeSecurityRequirementLists(values1, values2));
    }

    if (values1.get(0) instanceof Parameter) {
        return Optional.of(mergeParameterLists(values1, values2));
    }

    List merged = new ArrayList<>(values1.size() + values2.size());
    merged.addAll(values1);
    merged.addAll(values2);
    return Optional.of(merged);
}
 

/**
 * Filters the given model.
 * 
 * @param filter
 * @param model
 */
private static void filterParameter(OASFilter filter, Parameter model) {
    if (model != null) {
        filterContent(filter, model.getContent());
        filterSchema(filter, model.getSchema());
        if (model.getSchema() != null && filter.filterSchema(model.getSchema()) == null) {
            model.setSchema(null);
        }
    }
}
 

public static boolean isHidden(Parameter parameter) {
    return parameter != null
            && parameter.getExtensions() != null
            && !parameter.getExtensions().isEmpty()
            && parameter.getExtensions().containsKey(HIDDEN)
            && parameter.getExtensions().get(HIDDEN) != null
            && parameter.getExtensions().get(HIDDEN).equals(true);
}
 

/**
 * Process the JAX-RS Operation methods
 * 
 * @param context the scanning context
 * @param resourceClass the class containing the methods
 * @param openApi the OpenApi model being processed
 * @param locatorPathParameters path parameters
 */
private void processResourceMethods(final AnnotationScannerContext context,
        final ClassInfo resourceClass,
        OpenAPI openApi,
        List<Parameter> locatorPathParameters) {

    // Process tags (both declarations and references).
    Set<String> tagRefs = processTags(resourceClass, openApi, false);

    // Process exception mapper to auto generate api response based on method exceptions
    Map<DotName, AnnotationInstance> exceptionAnnotationMap = processExceptionMappers(context);

    for (MethodInfo methodInfo : getResourceMethods(context, resourceClass)) {
        final AtomicInteger resourceCount = new AtomicInteger(0);

        JaxRsConstants.HTTP_METHODS
                .stream()
                .filter(methodInfo::hasAnnotation)
                .map(DotName::withoutPackagePrefix)
                .map(PathItem.HttpMethod::valueOf)
                .forEach(httpMethod -> {
                    resourceCount.incrementAndGet();
                    processResourceMethod(context, resourceClass, methodInfo, httpMethod, openApi, tagRefs,
                            locatorPathParameters, exceptionAnnotationMap);
                });

        if (resourceCount.get() == 0 && methodInfo.hasAnnotation(JaxRsConstants.PATH)) {
            processSubResource(context, resourceClass, methodInfo, openApi, locatorPathParameters);
        }
    }
}
 

/**
 * Determines if the parameter is eligible to have a pattern constraint
 * applied to its schema.
 * 
 * @param param the parameter
 * @return true if the parameter may have the patter applied, otherwise false
 */
static boolean templateParameterPatternEligible(Parameter param) {
    return Parameter.In.PATH.equals(param.getIn())
            && !Style.MATRIX.equals(param.getStyle())
            && param.getSchema() != null
            && SchemaType.STRING.equals(param.getSchema().getType())
            && param.getSchema().getPattern() == null;
}
 

/**
 * Returns true only if the given {@link Parameter} has a schema defined
 * for it. A schema can be defined either via the parameter's "schema"
 * property, or any "content.*.schema" property.
 * 
 * @param parameter Parameter
 * @return Whether the parameter has a schema
 */
public static boolean parameterHasSchema(Parameter parameter) {
    if (parameter.getSchema() != null) {
        return true;
    }
    Map<String, MediaType> mediaTypes = getMediaTypesOrEmpty(parameter.getContent());
    if (!mediaTypes.isEmpty()) {
        for (MediaType mediaType : mediaTypes.values()) {
            if (mediaType.getSchema() != null) {
                return true;
            }
        }
    }
    return false;
}
 

public List<Parameter> getAllParameters() {
    List<Parameter> all = new ArrayList<>();

    if (pathItemParameters != null) {
        all.addAll(pathItemParameters);
    }

    if (operationParameters != null) {
        all.addAll(operationParameters);
    }

    return all;
}
 

/**
 * Reads a {@link Parameter} OpenAPI node.
 * 
 * @param node json list
 * @return List of Parameter model
 */
public static Optional<List<Parameter>> readParameterList(final JsonNode node) {
    if (node != null && node.isArray()) {
        IoLogging.log.jsonList("Parameter");
        List<Parameter> params = new ArrayList<>();
        ArrayNode arrayNode = (ArrayNode) node;
        for (JsonNode paramNode : arrayNode) {
            params.add(ParameterReader.readParameter(paramNode));
        }
        return Optional.of(params);
    }
    return Optional.empty();
}
 

/**
 * Reads the {@link Parameter} OpenAPI nodes.
 * 
 * @param node json map of Parameters
 * @return Map of Parameter model
 */
public static Map<String, Parameter> readParameters(final JsonNode node) {
    if (node == null || !node.isObject()) {
        return null;
    }
    IoLogging.log.jsonMap("Parameters");
    Map<String, Parameter> parameters = new LinkedHashMap<>();
    for (Iterator<String> fieldNames = node.fieldNames(); fieldNames.hasNext();) {
        String fieldName = fieldNames.next();
        JsonNode childNode = node.get(fieldName);
        parameters.put(fieldName, readParameter(childNode));
    }

    return parameters;
}
 

/**
 * Reads a parameter 'in' property.
 * 
 * @param node json node
 * @return In enum
 */
private static Parameter.In readParameterIn(final JsonNode node) {
    if (node == null || !node.isTextual()) {
        return null;
    }
    return PARAMETER_IN_LOOKUP.get(node.asText());
}
 

/**
 * Reads a parameter style.
 * 
 * @param node the json node
 * @return style enum
 */
private static Parameter.Style readParameterStyle(final JsonNode node) {
    if (node == null || !node.isTextual()) {
        return null;
    }
    return PARAMETER_STYLE_LOOKUP.get(node.asText());
}
 

/**
 * Writes a map of {@link Parameter} to the JSON tree.
 * 
 * @param parent the parent json node
 * @param parameters map of Parameter models
 */
public static void writeParameters(ObjectNode parent, Map<String, Parameter> parameters) {
    if (parameters == null) {
        return;
    }
    ObjectNode parametersNode = parent.putObject(ComponentsConstant.PROP_PARAMETERS);
    for (Map.Entry<String, Parameter> entry : parameters.entrySet()) {
        writeParameter(parametersNode, entry.getValue(), entry.getKey());
    }
}
 

/**
 * Writes a {@link Parameter} object to the JSON tree.
 * 
 * @param parent
 * @param model
 * @param name
 */
private static void writeParameter(ObjectNode parent, Parameter model, String name) {
    if (model == null) {
        return;
    }
    ObjectNode node = parent.putObject(name);
    writeParameter(node, model);
}
 

/**
 * Writes a list of {@link Parameter} to the JSON tree.
 * 
 * @param parent the parent json node
 * @param models list of Parameter models
 */
public static void writeParameterList(ObjectNode parent, List<Parameter> models) {
    if (models == null) {
        return;
    }
    ArrayNode node = parent.putArray(ComponentsConstant.PROP_PARAMETERS);
    for (Parameter model : models) {
        ObjectNode paramNode = node.addObject();
        writeParameter(paramNode, model);
    }
}
 

/**
 * Test method for
 * {@link OASFactoryResolverImpl#createObject(java.lang.Class)}.
 */
@SuppressWarnings({ "rawtypes", "unchecked" })
@Test
public void testCreateObject_All() {
    Class modelClasses[] = { APIResponse.class, APIResponses.class, Callback.class, Components.class,
            Contact.class, Content.class, Discriminator.class, Encoding.class, Example.class,
            ExternalDocumentation.class, Header.class, Info.class, License.class, Link.class, MediaType.class,
            OAuthFlow.class, OAuthFlows.class, OpenAPI.class, Operation.class, Parameter.class, PathItem.class,
            Paths.class, RequestBody.class, Schema.class, SecurityRequirement.class,
            SecurityScheme.class, Server.class, ServerVariable.class, Tag.class, XML.class };
    for (Class modelClass : modelClasses) {
        Constructible object = OASFactory.createObject(modelClass);
        Assert.assertNotNull(object);
    }
}
 

private String createReference(Reference<?> r, String v) {
    final StringBuilder sb = new StringBuilder();
    if (r instanceof APIResponse) {
        sb.append("#/components/responses/");
    }
    else if (r instanceof Callback) {
        sb.append("#/components/callbacks/");
    }
    else if (r instanceof Example) {
        sb.append("#/components/examples/");
    }
    else if (r instanceof Header) {
        sb.append("#/components/headers/");
    }
    else if (r instanceof Link) {
        sb.append("#/components/links/");
    }
    else if (r instanceof Parameter) {
        sb.append("#/components/parameters/");
    }
    else if (r instanceof PathItem) {
        sb.append("http://www.abc.def.ghi/");
    }
    else if (r instanceof RequestBody) {
        sb.append("#/components/requestBodies/");
    }
    else if (r instanceof Schema) {
        sb.append("#/components/schemas/");
    }
    else if (r instanceof SecurityScheme) {
        sb.append("#/components/securitySchemes/");
    }
    sb.append(v);
    return sb.toString();
}
 

@Override
public Parameter filterParameter(Parameter parameter) {
    if("The user name for login".equals(parameter.getDescription())){
        parameter.setDescription("filterParameter - The user name for login");
    }
    else if("The password for login in clear text".equals(parameter.getDescription())){
        return null; //remove parameter
    }
    return parameter;
}