From d0f8419ad5f688e409071183c7e1822f42762810 Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 6 Sep 2024 18:54:00 +0200 Subject: [PATCH 1/5] docs: add unit test --- docs/faq.md | 34 ++++++++++++++++++++++++++++++ src/components/HomepageFeatures.js | 27 ++++++++++++++++++++---- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 83d801a..b2644a4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -20,6 +20,40 @@ Either create a custom spring controller to serve the file or [serve static reso Note: `springwolf-ui` doesn't support the full AsyncAPI spec. +### Unit test verification + +With the AsyncApi artifact (i.e. at `src/test/resources/asyncapi.json) checked into the repository, +a unit test can verify that the current code still matches the expected AsyncApi specification. +Additionally, a diff reveals (un)expected changes. + +Example unit test: +```java +@SpringBootTest( + classes = {SpringwolfKafkaExampleApplication.class}, + webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) +class ApiIntegrationTest { + + @Autowired + private TestRestTemplate restTemplate; + + @Test + void asyncApiResourceArtifactTest() throws IOException { + String url = "/springwolf/docs"; + String actual = restTemplate.getForObject(url, String.class); + + // writing the actual file can be useful for debugging (remember: gitignore) + Files.writeString(Path.of("src", "test", "resources", "asyncapi.actual.json"), actual); + + InputStream s = this.getClass().getResourceAsStream("/asyncapi.json"); + String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim(); + + assertEquals(expected, actual); + } +} +``` + +For a full example, check the [springwolf-kafka-example ApiIntegrationTest](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/test/java/io/github/springwolf/examples/kafka/ApiIntegrationTest.java) + ## Troubleshooting ### Show `debug` output in the logs diff --git a/src/components/HomepageFeatures.js b/src/components/HomepageFeatures.js index 9bcd912..0ab72c0 100644 --- a/src/components/HomepageFeatures.js +++ b/src/components/HomepageFeatures.js @@ -8,7 +8,7 @@ const FeatureList = [ title: 'Effortless API documentation', description: ( <> - Springwolf uses metadata already provided in the code + Springwolf uses metadata already provided in the code to automatically create documentation. ), @@ -26,7 +26,8 @@ const FeatureList = [ title: 'Powered by AsyncAPI v3', description: ( <> - The generated documentation is compliant with the AsyncAPI specification. + The generated documentation is compliant with the + AsyncAPI specification. ), }, @@ -34,7 +35,8 @@ const FeatureList = [ title: 'Optional web-ui', description: ( <> - Single dependency ui for API testing including event publishing. + Single dependency for API testing including event publishing + (demo). ), }, @@ -50,7 +52,24 @@ const FeatureList = [ title: 'Integrate', description: ( <> - Generate documentation in your CI/CD pipeline and publish to tools like Backstage. + Generate documentation in your CI/CD pipeline and publish to tools like + Backstage. + + ), + }, + { + title: 'Verify', + description: ( + <> + Use an unit test to check for (un)expected changes. + + ), + }, + { + title: 'Participate', + description: ( + <> + Something missing? Features requests and contributions are welcome. ), }, From e507c8dae6b8b9bf8c427b72b486abd051deebbd Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 4 Oct 2024 13:24:12 +0200 Subject: [PATCH 2/5] docs: linting --- docs/behind-the-scenes.md | 2 +- docs/faq.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/behind-the-scenes.md b/docs/behind-the-scenes.md index 9a62843..7cdb2cf 100644 --- a/docs/behind-the-scenes.md +++ b/docs/behind-the-scenes.md @@ -51,5 +51,5 @@ They follow the same plugin model. ## Putting it all together -The `AsyncApiService` collects all the channels, schemas and general info and builds the AsyncApi document. +The `AsyncApiService` collects all the channels, schemas and general info and builds the AsyncAPI document. The controller access this services to serve the document to the UI. diff --git a/docs/faq.md b/docs/faq.md index b2644a4..1425f1f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -22,11 +22,12 @@ Note: `springwolf-ui` doesn't support the full AsyncAPI spec. ### Unit test verification -With the AsyncApi artifact (i.e. at `src/test/resources/asyncapi.json) checked into the repository, -a unit test can verify that the current code still matches the expected AsyncApi specification. +With the AsyncAPI artifact checked into the repository at `src/test/resources/asyncapi.json`, +a unit test can verify that the current code still matches the expected AsyncAPI specification. Additionally, a diff reveals (un)expected changes. Example unit test: + ```java @SpringBootTest( classes = {SpringwolfKafkaExampleApplication.class}, From 5b9a00c95252b5175fe689d40fb546b839f94eea Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 4 Oct 2024 13:30:49 +0200 Subject: [PATCH 3/5] docs: update to springwolf version 1.7.0 --- .../_springwolf_common_model_converters_groovy.gradle | 2 +- docs/snippets/_springwolf_common_model_converters_maven.xml | 2 +- docs/snippets/_springwolf_generic_binding_groovy.gradle | 2 +- docs/snippets/_springwolf_generic_binding_maven.xml | 2 +- docs/snippets/_springwolf_groovy.gradle | 4 ++-- docs/snippets/_springwolf_json_schema_groovy.gradle | 2 +- docs/snippets/_springwolf_json_schema_maven.xml | 2 +- ...ngwolf_kotlinx_serialization_model_converter_groovy.gradle | 2 +- ...springwolf_kotlinx_serialization_model_converter_maven.xml | 2 +- docs/snippets/_springwolf_maven.xml | 4 ++-- 10 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/snippets/_springwolf_common_model_converters_groovy.gradle b/docs/snippets/_springwolf_common_model_converters_groovy.gradle index ef2183e..9b38f87 100644 --- a/docs/snippets/_springwolf_common_model_converters_groovy.gradle +++ b/docs/snippets/_springwolf_common_model_converters_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-common-model-converters:1.4.0' + implementation 'io.github.springwolf:springwolf-common-model-converters:1.7.0' } diff --git a/docs/snippets/_springwolf_common_model_converters_maven.xml b/docs/snippets/_springwolf_common_model_converters_maven.xml index 1b53d14..da7e3af 100644 --- a/docs/snippets/_springwolf_common_model_converters_maven.xml +++ b/docs/snippets/_springwolf_common_model_converters_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-common-model-converters - 1.4.0 + 1.7.0 diff --git a/docs/snippets/_springwolf_generic_binding_groovy.gradle b/docs/snippets/_springwolf_generic_binding_groovy.gradle index b66d625..0bdd83c 100644 --- a/docs/snippets/_springwolf_generic_binding_groovy.gradle +++ b/docs/snippets/_springwolf_generic_binding_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-generic-binding:1.4.0' + implementation 'io.github.springwolf:springwolf-generic-binding:1.7.0' } diff --git a/docs/snippets/_springwolf_generic_binding_maven.xml b/docs/snippets/_springwolf_generic_binding_maven.xml index ce95684..b6013c4 100644 --- a/docs/snippets/_springwolf_generic_binding_maven.xml +++ b/docs/snippets/_springwolf_generic_binding_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-generic-binding - 1.4.0 + 1.7.0 diff --git a/docs/snippets/_springwolf_groovy.gradle b/docs/snippets/_springwolf_groovy.gradle index b58380b..28a6926 100644 --- a/docs/snippets/_springwolf_groovy.gradle +++ b/docs/snippets/_springwolf_groovy.gradle @@ -1,7 +1,7 @@ dependencies { // Provides the documentation API - implementation 'io.github.springwolf:springwolf-kafka:1.4.0' + implementation 'io.github.springwolf:springwolf-kafka:1.7.0' // Provides the UI - optional (recommended) - runtimeOnly 'io.github.springwolf:springwolf-ui:1.4.0' + runtimeOnly 'io.github.springwolf:springwolf-ui:1.7.0' } diff --git a/docs/snippets/_springwolf_json_schema_groovy.gradle b/docs/snippets/_springwolf_json_schema_groovy.gradle index d286ad9..7f9afbf 100644 --- a/docs/snippets/_springwolf_json_schema_groovy.gradle +++ b/docs/snippets/_springwolf_json_schema_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-json-schema:1.4.0' + implementation 'io.github.springwolf:springwolf-json-schema:1.7.0' } diff --git a/docs/snippets/_springwolf_json_schema_maven.xml b/docs/snippets/_springwolf_json_schema_maven.xml index 1c112ee..ef2c2ce 100644 --- a/docs/snippets/_springwolf_json_schema_maven.xml +++ b/docs/snippets/_springwolf_json_schema_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-json-schema - 1.4.0 + 1.7.0 diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle index ee5b45d..078e9bf 100644 --- a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.4.0' + implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.7.0' } diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml index fe76628..463c259 100644 --- a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-kotlinx-serialization-model-converter - 1.4.0 + 1.7.0 diff --git a/docs/snippets/_springwolf_maven.xml b/docs/snippets/_springwolf_maven.xml index daea306..ffce021 100644 --- a/docs/snippets/_springwolf_maven.xml +++ b/docs/snippets/_springwolf_maven.xml @@ -3,12 +3,12 @@ io.github.springwolf springwolf-kafka - 1.4.0 + 1.7.0 io.github.springwolf springwolf-ui - 1.4.0 + 1.7.0 From 5d52d9c841cda4fb8d81de078adf36d80a90fe0d Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 4 Oct 2024 13:58:23 +0200 Subject: [PATCH 4/5] docs: improve faq for using springwolf-ui only --- docs/faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 1425f1f..0beeab9 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,7 +16,7 @@ You can use `springwolf-ui` without any other Springwolf dependency. `springwolf-ui` will fetch any documentation available at the `springwolf/docs` path. It must be in `json` format (`yaml` isn't supported). -Either create a custom spring controller to serve the file or [serve static resources with spring](https://spring.io/guides/gs/serving-web-content/) and place your AsyncAPI document into `resources/springwolf/docs` (without file extension). +Either create a custom spring controller to serve the file or [serve static resources with spring](https://spring.io/guides/gs/serving-web-content/) and place AsyncAPI document file called `docs` (without file extension) into the folder `resources/springwolf`. Note: `springwolf-ui` doesn't support the full AsyncAPI spec. From eb8fad0da075d31ca819eb1291b3c67ec0e5b30b Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 4 Oct 2024 15:41:14 +0200 Subject: [PATCH 5/5] docs: re-order homepage feature --- src/components/HomepageFeatures.js | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/components/HomepageFeatures.js b/src/components/HomepageFeatures.js index 0ab72c0..0ec61e8 100644 --- a/src/components/HomepageFeatures.js +++ b/src/components/HomepageFeatures.js @@ -41,38 +41,38 @@ const FeatureList = [ ), }, { - title: 'Customizable', + title: 'Integrate', description: ( <> - Extend documentation using @AsyncListener and @AsyncPublisher. + Generate documentation in your CI/CD pipeline and publish to tools like Backstage. ), }, { - title: 'Integrate', + title: 'Customizable', description: ( <> - Generate documentation in your CI/CD pipeline and publish to tools like - Backstage. + Extend documentation using @AsyncListener and @AsyncPublisher. ), }, { - title: 'Verify', + title: 'Participate', description: ( <> - Use an unit test to check for (un)expected changes. + Something missing? Features requests and contributions are welcome. ), }, + { }, { - title: 'Participate', + title: 'Verify', description: ( <> - Something missing? Features requests and contributions are welcome. + Use an unit test to check for (un)expected changes. ), - }, + } ]; function Feature({Svg, title, description}) {