docs: add unit test (#95)

* docs: add unit test

* docs: linting

* docs: update to springwolf version 1.7.0

* docs: improve faq for using springwolf-ui only

* docs: re-order homepage feature

Author: timonback

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.

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

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'
 }

docs/snippets/_springwolf_common_model_converters_maven.xml

@@ -2,6 +2,6 @@
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-common-model-converters</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
 </dependencies>

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'
 }

docs/snippets/_springwolf_generic_binding_maven.xml

@@ -2,6 +2,6 @@
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-generic-binding</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
 </dependencies>

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'
 }

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'
 }

docs/snippets/_springwolf_json_schema_maven.xml

@@ -2,6 +2,6 @@
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-json-schema</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
 </dependencies>

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'
 }

docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml

@@ -2,6 +2,6 @@
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-kotlinx-serialization-model-converter</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
 </dependencies>

docs/snippets/_springwolf_maven.xml

@@ -3,12 +3,12 @@
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-kafka</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
     <!-- Provides the UI - optional (recommended) -->
     <dependency>
         <groupId>io.github.springwolf</groupId>
         <artifactId>springwolf-ui</artifactId>
-        <version>1.4.0</version>
+        <version>1.7.0</version>
     </dependency>
 </dependencies>

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,15 +26,25 @@ const FeatureList = [
     title: 'Powered by AsyncAPI v3',
     description: (
       <>
-        The generated documentation is compliant with the <Link to='https://www.asyncapi.com/'>AsyncAPI specification</Link>.
+        The generated documentation is compliant with the
+        <Link to='https://www.asyncapi.com/'>AsyncAPI specification</Link>.
       </>
     ),
   },
   {
     title: 'Optional web-ui',
     description: (
       <>
-        Single dependency ui for API testing including event publishing.
+        Single dependency for API testing including event publishing
+        (<Link to={'https://demo.springwolf.dev'}>demo</Link>).
+      </>
+    ),
+  },
+  {
+    title: 'Integrate',
+    description: (
+      <>
+        Generate documentation in your CI/CD pipeline and publish to tools like <Link to="https://backstage.io">Backstage</Link>.
       </>
     ),
   },
@@ -47,13 +57,22 @@ const FeatureList = [
     ),
   },
   {
-    title: 'Integrate',
+    title: 'Participate',
     description: (
       <>
-        Generate documentation in your CI/CD pipeline and publish to tools like <Link to="https://backstage.io">Backstage</Link>.
+        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}) {