Improve rest docs (#9)

gardenlinux · May 7, 2024 · e133719 · e133719
1 parent ffe42cc
commit e133719
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 10 deletions.
diff --git a/src/docs/asciidoc/index.adoc b/src/docs/asciidoc/index.adoc
@@ -4,30 +4,38 @@ Garden Linux Authors;
 :icons: font
 :source-highlighter: highlightjs
 
-== Lorem Ipsum
+== API Endpoints
+
+This document describes the HTTP API endpoints of Garden Linux Vulnerability Database.
+
+CAUTION: This document and the API are work in progress and subject to change at any time.
 
 === Check running app
 
+For verifying that the app is running and has a connection to the database, you may query the `readiness` endpoint:
+
 include::{snippets}/readiness/curl-request.adoc[]
 
+The expected response looks like this:
+
 include::{snippets}/readiness/http-response.adoc[]
 
 === Get a CVE by id
 
-Request
+To query a single CVE by its id, you maye use the `cves` endpoint:
 
 include::{snippets}/getCve/curl-request.adoc[]
 
-Response
+The expected response looks like this:
 
 include::{snippets}/getCve/http-response.adoc[]
 
 === Get a list of CVEs by distro
 
-Request
+To query all CVEs for a given distribution, you may use this endpoint:
 
 include::{snippets}/getCveForDistro/curl-request.adoc[]
 
-Response
+The expected response looks like this:
 
 include::{snippets}/getCveForDistro/http-response.adoc[]
diff --git a/src/test/java/io/gardenlinux/glvd/GlvdControllerTest.java b/src/test/java/io/gardenlinux/glvd/GlvdControllerTest.java
@@ -27,8 +27,7 @@
 
 import static io.restassured.RestAssured.given;
 import static org.hamcrest.Matchers.containsString;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.modifyUris;
-import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessRequest;
+import static org.springframework.restdocs.operation.preprocess.Preprocessors.*;
 import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;
 import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.documentationConfiguration;
 
@@ -81,7 +80,8 @@ void setUp(RestDocumentationContextProvider restDocumentation) {
     public void shouldGetCveById() {
         given(this.spec).accept("application/json")
                 .filter(document("getCve",
-                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort())))
+                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort()),
+                        preprocessResponse(prettyPrint())))
                 .when().port(this.port).get("/v1/cves/CVE-2024-1549")
 				.then().statusCode(HttpStatus.SC_OK).body("id", containsString("CVE-2024-1549"));
     }
@@ -97,7 +97,8 @@ void tryGetNonExistingCveById() {
     public void shouldReturnCvesForBookworm() {
         given(this.spec).accept("application/json")
                 .filter(document("getCveForDistro",
-                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort())))
+                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort()),
+                        preprocessResponse(prettyPrint())))
                 .when().port(this.port).get("/v1/cves/debian/debian_linux/bookworm")
 				.then().statusCode(HttpStatus.SC_OK);
     }
@@ -106,7 +107,8 @@ public void shouldReturnCvesForBookworm() {
     public void shouldBeReady() {
         given(this.spec)
                 .filter(document("readiness",
-                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort())))
+                        preprocessRequest(modifyUris().scheme("https").host("glvd.gardenlinux.io").removePort()),
+                        preprocessResponse(prettyPrint())))
                 .when().port(this.port).get("/readiness")
 				.then().statusCode(HttpStatus.SC_OK).body("dbCheck", containsString("true"));
     }