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 83d801a..0beeab9 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,10 +16,45 @@ 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. +### Unit test verification + +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}, + 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/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 diff --git a/src/components/HomepageFeatures.js b/src/components/HomepageFeatures.js index 9bcd912..0ec61e8 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,16 @@ 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). + + ), + }, + { + title: 'Integrate', + description: ( + <> + Generate documentation in your CI/CD pipeline and publish to tools like Backstage. ), }, @@ -47,13 +57,22 @@ const FeatureList = [ ), }, { - title: 'Integrate', + title: 'Participate', description: ( <> - Generate documentation in your CI/CD pipeline and publish to tools like Backstage. + Something missing? Features requests and contributions are welcome. ), }, + { }, + { + title: 'Verify', + description: ( + <> + Use an unit test to check for (un)expected changes. + + ), + } ]; function Feature({Svg, title, description}) {