Make documentation great again (Bonus)

Exposer “automagiquement” la documentation

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-resources</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/static/docs/</outputDirectory>
<resources>
<resource> <directory>${project.build.directory}/generated-docs</directory>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>

Cacher par défaut les trop grands éléments

.Response
[%collapsible]
====
include::{snippets}/getAllCompanies/http-response.adoc[]
====

Alléger la description des requêtes/réponses

public class ControllerTestUtils {    static OperationRequestPreprocessor preprocessRequest() {
return Preprocessors.preprocessRequest(removeHeaders("Content-Length", "X-CSRF-TOKEN"), prettyPrint());
}
static OperationResponsePreprocessor preprocessResponse() {
return Preprocessors.preprocessResponse(removeHeaders("Content-Length", "Pragma", "X-XSS-Protection", "Expires", "X-Frame-Options", "X-Content-Type-Options", "Cache-Control"), prettyPrint());
}
}
DELETE /companies/ID_1 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: localhost:8080
{
"id" : "ID_1",
"name" : "CoolCorp",
"location" : "Paris",
"creationDate" : "2021-11-06T11:03:53.066+00:00"
}
DELETE /companies/ID_1 HTTP/1.1
Host: localhost:8080
{
"id" : "ID_1",
"name" : "CoolCorp",
"location" : "Paris",
"creationDate" : "2021-11-06T11:01:34.532+00:00"
}

Générer un fichier OpenAPI

<dependency>
<groupId>com.epages</groupId>
<artifactId>restdocs-api-spec-mockmvc</artifactId>
<version>0.14.1</version>
<scope>test</scope>
</dependency>
import static com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper.document;
Nouvel aperçu des fichiers générés
<plugin>
<groupId>io.github.berkleytechnologyservices</groupId>
<artifactId>restdocs-spec-maven-plugin</artifactId>
<version>0.21</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<name>Demo Spring REST Docs</name>
<version>${project.version}</version>
<host>localhost:8080</host>
<outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
<filename>openapi</filename>
<specification>OPENAPI_V3</specification>
<description>API description for Demo Spring REST Docs service</description>
</configuration>
</execution>
</executions>
</plugin>
docker run -p 80:8080 swaggerapi/swagger-ui
Aperçu de la documentation rendue par Swagger UI

--

--

--

Developer @ConsenSys // Blockchain enthusiast // Engineer @ EPF

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alain Nicolas

Alain Nicolas

Developer @ConsenSys // Blockchain enthusiast // Engineer @ EPF

More from Medium

Inversion of Control (IoC)

No Such Method Exception in Java

Why you should not use “currentTimeMillis” when you calculate elapsed time?

What is JVM, JRE and JDK