Skip to content

[WIP] MicroProfile OpenAPI 4.2 updates #2466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
MikeEdgar wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[WIP] MicroProfile OpenAPI 4.2 updates #2466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
db4d461
[WIP] MicroProfile OpenAPI 4.2 updates
MikeEdgar Jan 28, 2026
17a89bb
Use MicroProfile OpenAPI 4.2-SNAPSHOT
MikeEdgar Jan 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions core/src/main/java/io/smallrye/openapi/runtime/io/ModelIO.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,10 +219,15 @@ public T read(AnnotationValue annotation) {
.orElse(null);
}

@SuppressWarnings("unchecked")
public <C extends Constructible> T read(Class<C> type, AnnotationInstance annotation) {
return read(type, annotation, new String[0]);
}

@SuppressWarnings("unchecked")
public <C extends Constructible> T read(Class<C> type, AnnotationInstance annotation, String... ignoredProperties) {
IoLogging.logger.singleAnnotation(annotation.name().toString());
BaseModel<C> model = (BaseModel<C>) OASFactory.createObject(type);
Set<String> ignoredNames = Set.of(ignoredProperties);

for (AnnotationValue annotationValue : annotation.values()) {
Object value = scannerContext().annotations().value(annotation, annotationValue);
Expand All @@ -234,7 +239,7 @@ public <C extends Constructible> T read(Class<C> type, AnnotationInstance annota
model.setRef(annotationValue.asString());
} else if ("extensions".equals(name) && Extensible.class.isAssignableFrom(type)) {
((BaseExtensibleModel<?>) model).setExtensions(extensionIO().readExtensible(annotation));
} else {
} else if (!ignoredNames.contains(name)) {
model.setProperty(name, value);
}
}
Expand Down
48 changes: 32 additions & 16 deletions core/src/main/java/io/smallrye/openapi/runtime/io/headers/HeaderIO.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,56 @@
package io.smallrye.openapi.runtime.io.headers;

import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.models.headers.Header;
import org.jboss.jandex.AnnotationInstance;
import org.jboss.jandex.AnnotationValue;

import io.smallrye.openapi.model.ReferenceType;
import io.smallrye.openapi.runtime.io.IOContext;
import io.smallrye.openapi.runtime.io.IoLogging;
import io.smallrye.openapi.runtime.io.MapModelIO;
import io.smallrye.openapi.runtime.io.Names;
import io.smallrye.openapi.runtime.io.ReferenceIO;

public class HeaderIO<V, A extends V, O extends V, AB, OB> extends MapModelIO<Header, V, A, O, AB, OB>
implements ReferenceIO<V, A, O, AB, OB> {

private static final String PROP_DESCRIPTION = "description";
private static final String PROP_SCHEMA = "schema";
private static final String PROP_ALLOW_EMPTY_VALUE = "allowEmptyValue";
private static final String PROP_REQUIRED = "required";
private static final String PROP_DEPRECATED = "deprecated";
private static final String PROP_EXAMPLE = "example";
private static final String PROP_EXAMPLES = "examples";

public HeaderIO(IOContext<V, A, O, AB, OB> context) {
super(context, Names.HEADER, Names.create(Header.class));
}

@Override
public Header read(AnnotationInstance annotation) {
IoLogging.logger.singleAnnotation("@Header");
Header header = OASFactory.createHeader();
header.setRef(ReferenceType.HEADER.refValue(annotation));
header.setDescription(value(annotation, PROP_DESCRIPTION));
header.setSchema(schemaIO().read(annotation.value(PROP_SCHEMA)));
header.setRequired(value(annotation, PROP_REQUIRED));
header.setDeprecated(value(annotation, PROP_DEPRECATED));
header.setAllowEmptyValue(value(annotation, PROP_ALLOW_EMPTY_VALUE));
header.setExtensions(extensionIO().readExtensible(annotation));
Header header = read(Header.class, annotation, "name");

if (header.getExample() != null || header.getExamples() != null) {
/*
* Save the header for later parsing. The schema may not yet be set
* so we do not know if it should be parsed.
*/
scannerContext().getUnparsedExamples().add(header);
}

return header;
}

@Override
protected boolean setProperty(Header model, AnnotationValue value) {
switch (value.name()) {
case PROP_SCHEMA:
model.setSchema(schemaIO().read(value));
return true;
case PROP_EXAMPLES:
model.setExamples(exampleObjectIO().readMap(value));
return true;
case PROP_EXAMPLE:
model.setExample(value.asString());
return true;
default:
break;
}

return false;
}
}
5 changes: 5 additions & 0 deletions core/src/main/java/io/smallrye/openapi/runtime/scanner/OpenApiAnnotationScanner.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.Paths;
import org.eclipse.microprofile.openapi.models.examples.Example;
import org.eclipse.microprofile.openapi.models.headers.Header;
import org.eclipse.microprofile.openapi.models.media.MediaType;
import org.eclipse.microprofile.openapi.models.media.Schema.SchemaType;
import org.eclipse.microprofile.openapi.models.parameters.Parameter;
Expand Down Expand Up @@ -417,6 +418,10 @@ private void parseExamples() {
MediaType mediaType = (MediaType) model;
parseExample(mediaType.getExample(), mediaType::setExample);
examples = mediaType.getExamples();
} else if (model instanceof Header) {
Header header = (Header) model;
parseExample(header.getExample(), header::setExample);
examples = header.getExamples();
}

if (examples != null) {
Expand Down
6 changes: 6 additions & 0 deletions core/src/main/java/io/smallrye/openapi/runtime/scanner/spi/AnnotationScanner.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
import java.util.stream.Stream;

import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.models.ExternalDocumentation;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.Operation;
import org.eclipse.microprofile.openapi.models.callbacks.Callback;
Expand Down Expand Up @@ -313,6 +314,11 @@ default Optional<Operation> processOperation(final AnnotationScannerContext cont
saveOperationId(context, resourceClass, method, operationId);
}

ExternalDocumentation externalDocs = context.io().extDocIO().read(method);
if (externalDocs != null) {
operation.setExternalDocs(externalDocs);
}

return Optional.of(operation);
}

Expand Down
15 changes: 14 additions & 1 deletion pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
<version.io.smallrye.jandex>3.5.3</version.io.smallrye.jandex>
<version.io.smallrye.smallrye-config>3.16.0</version.io.smallrye.smallrye-config>
<version.io.smallrye.smallrye-common-classloader>2.15.0</version.io.smallrye.smallrye-common-classloader>
<version.eclipse.microprofile.openapi>4.1.1</version.eclipse.microprofile.openapi>
<version.eclipse.microprofile.openapi>4.2-SNAPSHOT</version.eclipse.microprofile.openapi>
<version.kotlinx-metadata-jvm>0.9.0</version.kotlinx-metadata-jvm>
<version.org.hamcrest>1.3</version.org.hamcrest>
<version.org.hamcrest.java-hamcrest>2.0.0.0</version.org.hamcrest.java-hamcrest>
Expand Down Expand Up @@ -78,6 +78,19 @@
<tag>HEAD</tag>
</scm>

<repositories>
<repository>
<id>microprofile-snapshots</id>
<url>https://repo.eclipse.org/content/repositories/microprofile-snapshots/</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>

<modules>
<module>core</module>
<module>extension-jaxrs</module>
Expand Down
15 changes: 14 additions & 1 deletion testsuite/data/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<name>SmallRye: OpenAPI Test Data</name>

<properties>
<eclipse.microprofile.openapi.version>4.1.1</eclipse.microprofile.openapi.version>
<eclipse.microprofile.openapi.version>4.2-SNAPSHOT</eclipse.microprofile.openapi.version>
<kotlin.version>2.2.0</kotlin.version>
<java.version>17</java.version>
<maven.compiler.source>${java.version}</maven.compiler.source>
Expand All @@ -24,6 +24,19 @@
<quarkus.platform.version>3.31.1</quarkus.platform.version>
</properties>

<repositories>
<repository>
<id>microprofile-snapshots</id>
<url>https://repo.eclipse.org/content/repositories/microprofile-snapshots/</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>

<dependencyManagement>
<dependencies>
<dependency>
Expand Down