Skip to content

Commit d415473

Browse files
scholzjscholzj
authored
Add ExternalLink annotation to link to external API siuch as Gateway API (#12590)
Signed-off-by: Jakub Scholz <www@scholzj.com>
1 parent 6d21795 commit d415473

File tree

11 files changed

+113
-68
lines changed

11 files changed

+113
-68
lines changed

‎api/pom.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -321,8 +321,7 @@
321321
<argument>-classpath</argument>
322322
<argument>${project.basedir}${file.separator}target${file.separator}classes${path.separator}${project.basedir}${file.separator}..${file.separator}crd-generator${file.separator}target${file.separator}crd-generator-${project.version}.jar</argument>
323323
<argument>io.strimzi.crdgenerator.DocGenerator</argument>
324-
<argument>--linker</argument>
325-
<argument>io.strimzi.crdgenerator.KubeLinker</argument>
324+
<argument>--kubernetes-base-url</argument>
326325
<argument>https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/</argument>
327326
<argument>modules/appendix_crds.adoc</argument>
328327
<argument>io.strimzi.api.kafka.model.kafka.Kafka</argument>

‎crd-generator/src/main/java/io/strimzi/crdgenerator/DocGenerator.java‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import io.strimzi.crdgenerator.annotations.Crd;
1414
import io.strimzi.crdgenerator.annotations.Description;
1515
import io.strimzi.crdgenerator.annotations.DescriptionFile;
16+
import io.strimzi.crdgenerator.annotations.ExternalLink;
1617
import io.strimzi.crdgenerator.annotations.KubeLink;
1718
import io.strimzi.crdgenerator.annotations.PresentInVersions;
1819

@@ -89,7 +90,7 @@ private void usedIn(Class<?> cls, Map<Class<?>, Set<Class<?>>> usedIn) {
8990
Set<Property> memorableProperties = new HashSet<>();
9091

9192
for (Property property : properties(crApiVersion, cls).values()) {
92-
if (property.isAnnotationPresent(KubeLink.class)) {
93+
if (property.isAnnotationPresent(KubeLink.class) || property.isAnnotationPresent(ExternalLink.class)) {
9394
continue;
9495
}
9596

@@ -151,9 +152,8 @@ private void appendCommonTypeDoc(Crd crd, Class<?> cls) throws IOException {
151152
final Property property = entry.getValue();
152153
PropertyType propertyType = property.getType();
153154

154-
// Set the external link to Kubernetes docs or the link for fields distinguished by `type`
155-
KubeLink kubeLink = property.getAnnotation(KubeLink.class);
156-
String externalUrl = linker != null && kubeLink != null ? linker.link(kubeLink) : null;
155+
// Set the external link to some other docs
156+
String externalUrl = linker.link(property);
157157

158158
// Add the property name
159159
out.append("|").append(propertyName);
@@ -497,18 +497,8 @@ public static void main(String[] args) throws IOException, ClassNotFoundExceptio
497497
for (int i = 0; i < args.length; i++) {
498498
String arg = args[i];
499499
if (arg.startsWith("-")) {
500-
if ("--linker".equals(arg)) {
501-
String className = args[++i];
502-
Class<? extends Linker> linkerClass = classInherits(Class.forName(className), Linker.class);
503-
if (linkerClass != null) {
504-
try {
505-
linker = linkerClass.getConstructor(String.class).newInstance(args[++i]);
506-
} catch (ReflectiveOperationException e) {
507-
throw new RuntimeException("--linker option can't be handled", e);
508-
}
509-
} else {
510-
System.err.println(className + " is not a subclass of " + Linker.class.getName());
511-
}
500+
if ("--kubernetes-base-url".equals(arg)) {
501+
linker = new Linker(args[++i]);
512502
} else {
513503
throw new RuntimeException("Unsupported option " + arg);
514504
}

‎crd-generator/src/main/java/io/strimzi/crdgenerator/KubeLinker.java‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎crd-generator/src/main/java/io/strimzi/crdgenerator/Linker.java‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,65 @@
44
*/
55
package io.strimzi.crdgenerator;
66

7+
import io.strimzi.crdgenerator.annotations.ExternalLink;
78
import io.strimzi.crdgenerator.annotations.KubeLink;
89

910
/**
10-
* Interface for handling links in the documentation generator
11+
* Class for handling links in the documentation generator
1112
*/
12-
interface Linker {
13+
public class Linker {
14+
private final String baseUrl;
15+
16+
/**
17+
* Constructs the Linker and initializes the base URL to the Kubernetes documentation
18+
*
19+
* @param baseUrl The base URL to the Kubernetes documentation which should be used
20+
*/
21+
public Linker(String baseUrl) {
22+
// E.g. https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/
23+
this.baseUrl = baseUrl;
24+
}
25+
26+
/**
27+
* Creates the link based on the annotations on the property
28+
*
29+
* @param property Property to check the annotation on
30+
*
31+
* @return Returns the URL based on the annotation or null if no link annotation is present
32+
*/
33+
public String link(Property property) {
34+
KubeLink kubeLink = property.getAnnotation(KubeLink.class);
35+
ExternalLink externalLink = property.getAnnotation(ExternalLink.class);
36+
37+
if (kubeLink != null) {
38+
return link(kubeLink);
39+
} else if (externalLink != null) {
40+
return link(externalLink);
41+
} else {
42+
return null;
43+
}
44+
}
45+
1346
/**
14-
* Generates URL to some specific documentation
47+
* Generates URL to a specific page in the Kubernetes API reference.
1548
*
16-
* @param kubeLink Specifies the Kubernetes API which should the link point to
49+
* @param kubeLink The KubeLink annotation which specifies the Kubernetes API to link to
1750
*
1851
* @return An HTTP link deep-linking to the Kubernetes documentation
1952
*/
20-
String link(KubeLink kubeLink);
53+
private String link(KubeLink kubeLink) {
54+
// E.g. https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.11/#networkpolicyingressrule-v1-networking-k8s-io
55+
return baseUrl + "#" + kubeLink.kind() + "-" + kubeLink.version() + "-" + kubeLink.group().replace(".", "-");
56+
}
57+
58+
/**
59+
* Returns URL to a specific page in the API reference documentation of some other project.
60+
*
61+
* @param externalLink The ExternalLink annotation which specifies the external URL
62+
*
63+
* @return An HTTP URL
64+
*/
65+
private String link(ExternalLink externalLink) {
66+
return externalLink.url();
67+
}
2168
}

‎crd-generator/src/main/java/io/strimzi/crdgenerator/annotations/ExternalLink.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/*
2+
* Copyright Strimzi authors.
3+
* License: Apache License 2.0 (see the file LICENSE or http://apache.org/licenses/LICENSE-2.0.html).
4+
*/
5+
package io.strimzi.crdgenerator.annotations;
6+
7+
import java.lang.annotation.ElementType;
8+
import java.lang.annotation.Retention;
9+
import java.lang.annotation.RetentionPolicy;
10+
import java.lang.annotation.Target;
11+
12+
/**
13+
* Configure a link to some external API description. For a link to Kubernetes APi use the @{code @KubeLink} annotation.
14+
*/
15+
@Retention(RetentionPolicy.RUNTIME)
16+
@Target({ElementType.METHOD, ElementType.FIELD})
17+
public @interface ExternalLink {
18+
/**
19+
* Gets the URL to which the link should point.
20+
*
21+
* @return The URL to which the link should point
22+
*/
23+
String url();
24+
}

‎crd-generator/src/test/java/io/strimzi/crdgenerator/DocGeneratorTest.java‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,14 @@
1010
import java.io.IOException;
1111
import java.io.StringWriter;
1212

13-
import static io.strimzi.crdgenerator.DocGenerator.classInherits;
1413
import static java.util.Collections.singletonList;
15-
import static org.hamcrest.CoreMatchers.is;
16-
import static org.hamcrest.CoreMatchers.notNullValue;
17-
import static org.hamcrest.MatcherAssert.assertThat;
1814
import static org.junit.jupiter.api.Assertions.assertEquals;
1915

2016
public class DocGeneratorTest {
2117
@Test
22-
public void simpleTest() throws IOException, ClassNotFoundException {
23-
assertThat(classInherits(Class.forName("io.strimzi.crdgenerator.KubeLinker"), Linker.class), is(notNullValue()));
18+
public void simpleTest() throws IOException {
2419
StringWriter w = new StringWriter();
25-
DocGenerator crdGenerator = new DocGenerator(ApiVersion.V1, 1, singletonList(ExampleCrd.class), w, new KubeLinker("{KubeApiReferenceBase}"));
20+
DocGenerator crdGenerator = new DocGenerator(ApiVersion.V1, 1, singletonList(ExampleCrd.class), w, new Linker("{KubeApiReferenceBase}"));
2621
crdGenerator.generate(ExampleCrd.class);
2722
String s = w.toString();
2823
assertEquals(CrdTestUtils.readResource("simpleTest.adoc"), s);

‎crd-generator/src/test/java/io/strimzi/crdgenerator/ExampleCrd.java‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import io.strimzi.crdgenerator.annotations.Crd;
1919
import io.strimzi.crdgenerator.annotations.Description;
2020
import io.strimzi.crdgenerator.annotations.Example;
21+
import io.strimzi.crdgenerator.annotations.ExternalLink;
2122
import io.strimzi.crdgenerator.annotations.KubeLink;
2223
import io.strimzi.crdgenerator.annotations.Minimum;
2324
import io.strimzi.crdgenerator.annotations.MinimumItems;
@@ -66,7 +67,7 @@
6667
"rawList", "listOfRawList", "arrayOfList", "arrayOfRawList", "listOfArray", "arrayOfTypeVar", "listOfTypeVar",
6768
"arrayOfBoundTypeVar", "listOfBoundTypeVar", "arrayOfBoundTypeVar2", "listOfBoundTypeVar2",
6869
"listOfWildcardTypeVar1", "listOfWildcardTypeVar2", "listOfWildcardTypeVar3", "listOfWildcardTypeVar4",
69-
"listOfCustomizedEnum", "listOfNormalEnum", "listOfMaps", "either", "or", "status", "spec"})
70+
"listOfCustomizedEnum", "listOfNormalEnum", "listOfMaps", "either", "or", "status", "spec", "external"})
7071
public class ExampleCrd<T, U extends Number, V extends U> extends CustomResource {
7172

7273
private String ignored;
@@ -143,6 +144,8 @@ public class ExampleCrd<T, U extends Number, V extends U> extends CustomResource
143144

144145
public String or;
145146

147+
private String external;
148+
146149
@Description("Example of complex type.")
147150
@JsonInclude(JsonInclude.Include.NON_NULL)
148151
@JsonPropertyOrder({"foo", "bar"})
@@ -353,4 +356,13 @@ public Affinity getAffinity() {
353356
public void setAffinity(Affinity affinity) {
354357
this.affinity = affinity;
355358
}
359+
360+
@ExternalLink(url = "https://gateway-api.sigs.k8s.io/reference/spec/#parentreference")
361+
public String getExternal() {
362+
return external;
363+
}
364+
365+
public void setExternal(String external) {
366+
this.external = external;
367+
}
356368
}

‎crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,9 @@
128128
|spec
129129
|object
130130
|
131+
|external
132+
|https://gateway-api.sigs.k8s.io/reference/spec/#parentreference[String]
133+
|
131134
|====
132135

133136
[id='type-ObjectProperty-{context}']

‎crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTest.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -607,6 +607,8 @@ spec:
607607
spec:
608608
type: object
609609
properties: {}
610+
external:
611+
type: string
610612
oneOf:
611613
- properties:
612614
either: {}
@@ -1214,6 +1216,8 @@ spec:
12141216
spec:
12151217
type: object
12161218
properties: {}
1219+
external:
1220+
type: string
12171221
oneOf:
12181222
- properties:
12191223
either: {}

‎crd-generator/src/test/resources/io/strimzi/crdgenerator/simpleTestHelmMetadata.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -613,6 +613,8 @@ spec:
613613
spec:
614614
type: object
615615
properties: {}
616+
external:
617+
type: string
616618
oneOf:
617619
- properties:
618620
either: {}
@@ -1220,6 +1222,8 @@ spec:
12201222
spec:
12211223
type: object
12221224
properties: {}
1225+
external:
1226+
type: string
12231227
oneOf:
12241228
- properties:
12251229
either: {}

0 commit comments

Comments
 (0)