1 /*
2 * The contents of this file are subject to the terms of the Common Development and
3 * Distribution License (the License). You may not use this file except in compliance with the
4 * License.
5 *
6 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
7 * specific language governing permission and limitations under the License.
8 *
9 * When distributing Covered Software, include this CDDL Header Notice in each file and include
10 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
11 * Header, with the fields enclosed by brackets [] replaced by your own identifying
12 * information: "Portions copyright [year] [name of copyright owner]".
13 *
14 * Copyright 2016 ForgeRock AS.
15 * Portions Copyright 2026 Wren Security.
16 */
17 package org.forgerock.api.transform;
18
19 import com.fasterxml.jackson.annotation.JsonIgnore;
20 import com.fasterxml.jackson.annotation.JsonProperty;
21 import io.swagger.v3.oas.models.media.Schema;
22 import io.swagger.v3.oas.models.parameters.Parameter;
23 import java.util.List;
24 import org.forgerock.util.i18n.LocalizableString;
25
26 /**
27 * Localizable {@link Parameter} base class.
28 *
29 * <p>In OpenAPI 3.0, all parameter types (header, query, path) are represented by a single
30 * {@code Parameter} class with an {@code in} field.
31 */
32 class LocalizableParameter extends Parameter implements LocalizableDescription<Parameter> {
33
34 private LocalizableString description;
35
36 @Override
37 public LocalizableParameter description(LocalizableString desc) {
38 this.description = desc;
39 return this;
40 }
41
42 @Override
43 public LocalizableParameter description(String description) {
44 setDescription(description);
45 return this;
46 }
47
48 @Override
49 public void setDescription(String description) {
50 super.setDescription(description);
51 this.description = new LocalizableString(description);
52 }
53
54 @Override
55 @JsonProperty("description")
56 public LocalizableString getLocalizableDescription() {
57 return description;
58 }
59
60 @Override
61 @JsonIgnore
62 public String getDescription() {
63 return super.getDescription();
64 }
65
66 /**
67 * Convenience method to set the type on the parameter's schema.
68 * In OpenAPI 3.0, parameter type is expressed through the schema.
69 *
70 * @param type The type string (e.g., "string", "integer", "boolean").
71 */
72 public void setType(String type) {
73 ensureSchema().setType(type);
74 }
75
76 /**
77 * Convenience method to set enum values on the parameter's schema.
78 *
79 * @param enumValues The enum values.
80 */
81 @SuppressWarnings({ "unchecked" })
82 public void setEnum(List<?> enumValues) {
83 ensureSchema().setEnum(enumValues);
84 }
85
86 /**
87 * Convenience method to set the collection format equivalent.
88 * In OpenAPI 3.0, "csv" collection format maps to style=form, explode=false for query parameters.
89 *
90 * @param collectionFormat The collection format (e.g., "csv").
91 */
92 public void setCollectionFormat(String collectionFormat) {
93 if ("csv".equals(collectionFormat)) {
94 setStyle(StyleEnum.FORM);
95 setExplode(false);
96 }
97 }
98
99 /**
100 * Convenience method to set default value on the parameter's schema.
101 *
102 * @param defaultValue The default value.
103 */
104 public void setDefault(String defaultValue) {
105 ensureSchema().setDefault(defaultValue);
106 }
107
108 @SuppressWarnings("rawtypes")
109 private Schema ensureSchema() {
110 Schema schema = getSchema();
111 if (schema == null) {
112 schema = new Schema<>();
113 setSchema(schema);
114 }
115 return schema;
116 }
117
118 }