Feature/add auto doc

README.md

@@ -23,6 +23,7 @@ This project provides an authentication API to be used by other applications to
   - [Microsoft Entra Azure AD oAuth2](#microsoft-entra-azure-ad-oauth2)
   - [Commands cheat-sheet](#commands-cheat-sheet)
     - [Simplified sequence diagram](#simplified-sequence-diagram)
+  - [Spring REST Docs](#spring-rest-docs)
 - [Sources](#sources)
 
 ## Getting Started
@@ -169,3 +170,15 @@ Check if the project's structure is valid
 [Microsoft oAuth2 grant flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow)
 
 ---
+
+## Spring REST Docs
+
+The application contains an automated documentation from the Spring REST Docs package. The documentation is created when running the application in test environment.
+
+It creates an index.adoc file in the "src/asciidoc" folder and an index.html page in the "docs" folder.
+
+Link to the generated index.adoc : [src/asciidoc/index.adoc](src/asciidoc/index.adoc)
+
+Link to the generated index.html : [docs/index.html](docs/index.html)
+
+Link to the doc on GitHub : [https://orifinformatique.github.io/spring-auth/](https://orifinformatique.github.io/spring-auth/)

application.properties-dist

@@ -1,31 +1,3 @@
-#          ╭──────────────────────────────────────────────────────────╮
-#          │                          oauth2                          │
-#          ╰──────────────────────────────────────────────────────────╯
-### Azure ###
-custom.azure.account.tenant-id=
-
-# Azure Provider Configuration
-spring.security.oauth2.client.provider.azure.issuer-uri=https://login.microsoftonline.com/${custom.azure.account.tenant-id}/v2.0
-spring.security.oauth2.client.provider.azure.authorization-uri=https://login.microsoftonline.com/${custom.azure.account.tenant-id}/oauth2/v2.0/authorize
-spring.security.oauth2.client.provider.azure.token-uri=https://login.microsoftonline.com/${custom.azure.account.tenant-id}/oauth2/v2.0/token
-spring.security.oauth2.client.provider.azure.user-info-uri=https://graph.microsoft.com/oidc/userinfo
-spring.security.oauth2.client.provider.azure.jwk-set-uri=https://login.microsoftonline.com/${custom.azure.account.tenant-id}/discovery/v2.0/keys
-spring.security.oauth2.client.provider.azure.user-name-attribute=email
-
-# Azure Client Configuration
-spring.security.oauth2.client.registration.azure.client-id=
-spring.security.oauth2.client.registration.azure.client-secret=
-spring.security.oauth2.client.registration.azure.client-authentication-method=client_secret_post
-spring.security.oauth2.client.registration.azure.authorization-grant-type=authorization_code
-spring.security.oauth2.client.registration.azure.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
-spring.security.oauth2.client.registration.azure.scope=openid,profile,email,User.Read
-spring.security.oauth2.client.registration.azure.client-name=Azure
-
-### Google exemple for multiple provider login ###
-spring.security.oauth2.client.registration.google.client-id=0
-spring.security.oauth2.client.registration.google.client-secret=0
-spring.security.oauth2.client.registration.google.scope=0
-
 ### Logging levels ###
 logging.level.root=ERROR
 logging.level.ch.sectioninformatique=ERROR

compose.yml

@@ -9,6 +9,9 @@ services:
       context: .
       dockerfile: Dockerfile
       target: "${ENVIRONMENT}" # Use the environment variable to target the desired stage
+    volumes:
+      - ./src/asciidoc:/app/build/generated-snippets
+      - ./docs:/app/build/generated-snippets-html
     environment:
       # Pass environment variables to the container and the Spring Boot app
       SPRING_PROFILES_ACTIVE: "${ENVIRONMENT}"
@@ -32,11 +35,11 @@ services:
       MARIADB_ROOT_PASSWORD: "${DB_PASSWORD}"
       MARIADB_DATABASE: "${ENVIRONMENT}_db"
     volumes:
-    - ./init.sql:/docker-entrypoint-initdb.d/init.sql
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
     networks:
       - spring_network
     healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
       interval: 10s
       timeout: 5s
       retries: 5

env-dist

@@ -15,4 +15,11 @@ TEST_SPRING_DATASOURCE_URL=jdbc:mariadb://db:3306/test_db
 
 # User name and password used by Docker to create the database container
 DB_USERNAME=root
-DB_PASSWORD=pwd
+DB_PASSWORD=pwd
+
+# Azure OAuth2 settings
+# Set these values according to your Azure app registration
+AZURE_REDIRECT_BASE_URL=http://localhost:8080
+AZURE_TENANT_ID=
+AZURE_CLIENT_ID=
+AZURE_CLIENT_SECRET=

pom.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <parent>
         <groupId>org.springframework.boot</groupId>
@@ -11,7 +11,7 @@
     </parent>
     <groupId>ch.sectioninformatique</groupId>
     <artifactId>spring-auth</artifactId>
-    <version>0.1.0</version>
+    <version>0.1.1-SNAPSHOT</version>
     <name>spring-auth</name>
     <description>Authentication API to be used by other applications to identify their users</description>
     <url />
@@ -37,6 +37,12 @@
             <artifactId>dotenv-java</artifactId>
             <version>3.0.0</version>
         </dependency>
+        <!-- Spring REST Docs for MockMvc (JUnit 5 supported) -->
+        <dependency>
+            <groupId>org.springframework.restdocs</groupId>
+            <artifactId>spring-restdocs-mockmvc</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-data-jpa</artifactId>
@@ -46,7 +52,7 @@
             <artifactId>spring-boot-starter-web</artifactId>
         </dependency>
         <dependency>
-        <groupId>org.springframework.boot</groupId>
+            <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-validation</artifactId>
         </dependency>
         <dependency>
@@ -57,7 +63,6 @@
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
-            <version>1.18.36</version>
             <scope>provided</scope>
         </dependency>
         <dependency>
@@ -81,6 +86,12 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>
             <scope>test</scope>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.junit.vintage</groupId>
+                    <artifactId>junit-vintage-engine</artifactId>
+                </exclusion>
+             </exclusions>
         </dependency>
         <dependency>
             <groupId>org.springframework.security</groupId>
@@ -95,7 +106,6 @@
         <dependency>
             <groupId>jakarta.validation</groupId>
             <artifactId>jakarta.validation-api</artifactId>
-            <version>3.0.2</version>
         </dependency>
         <dependency>
             <groupId>org.mapstruct</groupId>
@@ -121,6 +131,7 @@
             <version>4.0.0</version>
             <scope>provided</scope>
         </dependency>
+        <!-- (duplicate removed above) -->
     </dependencies>
 
     <build>
@@ -143,6 +154,67 @@
                     </annotationProcessorPaths>
                 </configuration>
             </plugin>
+            <plugin> 
+                <groupId>org.asciidoctor</groupId>
+                <artifactId>asciidoctor-maven-plugin</artifactId>
+                <version>2.2.1</version>
+                <executions>
+                    <execution>
+                        <id>generate-docs</id>
+                        <phase>prepare-package</phase> 
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <backend>html</backend>
+                            <doctype>book</doctype>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>convert-to-html</id>
+                        <phase>generate-resources</phase> 
+                        <goals>
+                            <goal>process-asciidoc</goal>
+                        </goals>
+                        <configuration>
+                            <sourceDirectory>src/asciidoc</sourceDirectory>
+                            <sourceDocumentName>index.adoc</sourceDocumentName>
+                            <outputDirectory>/app/build/generated-snippets-html</outputDirectory> 
+                        </configuration>
+                    </execution>
+                </executions>
+                <dependencies>
+                    <dependency> 
+                        <groupId>org.springframework.restdocs</groupId>
+                        <artifactId>spring-restdocs-asciidoctor</artifactId>
+                        <version>${spring-restdocs.version}</version>
+                    </dependency>
+                </dependencies>
+            </plugin>
+            <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.outputDirectory}/static/docs
+                            </outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>
+                                        ${project.build.directory}/generated-docs
+                                    </directory>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 </project>

src/asciidoc/index.adoc

@@ -0,0 +1,37 @@
+= Spring Auth API Documentation
+
+== User Endpoints
+
+=== Get Authenticated User
+This is an example output for the `GET /users/me` endpoint.
+
+.request
+include::users/me/http-request.adoc[]
+
+.response
+include::users/me/http-response.adoc[]
+
+It gives informations about the authenticated user.
+
+
+=== Get All Users
+This is an example output for the `GET /users/all` endpoint.
+
+.request
+include::users/all/http-request.adoc[]
+
+.response
+include::users/all/http-response.adoc[]
+
+It gives informations about all users.
+
+=== Promote User to Manager
+This is an example output for the `PUT /users/{userId}/promote-manager` endpoint.
+
+.request
+include::users/promote-manager/http-request.adoc[]
+
+.response
+include::users/promote-manager/http-response.adoc[]
+
+It promotes a user to the "MANAGER" role.

src/asciidoc/users/all/curl-request.adoc

@@ -0,0 +1,5 @@
+[source,bash]
+----
+$ curl 'http://localhost:8080/users/all' -i -X GET \
+    -H 'Accept: application/json'
+----

src/asciidoc/users/all/http-request.adoc

@@ -0,0 +1,7 @@
+[source,http,options="nowrap"]
+----
+GET /users/all HTTP/1.1
+Accept: application/json
+Host: localhost:8080
+
+----

src/asciidoc/users/all/http-response.adoc

@@ -0,0 +1,38 @@
+[source,http,options="nowrap"]
+----
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 698
+
+[ {
+  "id" : 1,
+  "firstName" : "John",
+  "lastName" : "Doe",
+  "login" : "john@test.com",
+  "password" : "pass",
+  "createdAt" : null,
+  "updatedAt" : null,
+  "mainRole" : null,
+  "authorities" : [ ],
+  "accountNonExpired" : true,
+  "accountNonLocked" : true,
+  "credentialsNonExpired" : true,
+  "username" : "john@test.com",
+  "enabled" : true
+}, {
+  "id" : 2,
+  "firstName" : "Jane",
+  "lastName" : "Smith",
+  "login" : "jane@test.com",
+  "password" : "pass",
+  "createdAt" : null,
+  "updatedAt" : null,
+  "mainRole" : null,
+  "authorities" : [ ],
+  "accountNonExpired" : true,
+  "accountNonLocked" : true,
+  "credentialsNonExpired" : true,
+  "username" : "jane@test.com",
+  "enabled" : true
+} ]
+----

src/asciidoc/users/all/httpie-request.adoc

@@ -0,0 +1,5 @@
+[source,bash]
+----
+$ http GET 'http://localhost:8080/users/all' \
+    'Accept:application/json'
+----

src/asciidoc/users/all/request-body.adoc

@@ -0,0 +1,4 @@
+[source,options="nowrap"]
+----
+
+----

src/asciidoc/users/all/response-body.adoc

@@ -0,0 +1,34 @@
+[source,json,options="nowrap"]
+----
+[ {
+  "id" : 1,
+  "firstName" : "John",
+  "lastName" : "Doe",
+  "login" : "john@test.com",
+  "password" : "pass",
+  "createdAt" : null,
+  "updatedAt" : null,
+  "mainRole" : null,
+  "authorities" : [ ],
+  "accountNonExpired" : true,
+  "accountNonLocked" : true,
+  "credentialsNonExpired" : true,
+  "username" : "john@test.com",
+  "enabled" : true
+}, {
+  "id" : 2,
+  "firstName" : "Jane",
+  "lastName" : "Smith",
+  "login" : "jane@test.com",
+  "password" : "pass",
+  "createdAt" : null,
+  "updatedAt" : null,
+  "mainRole" : null,
+  "authorities" : [ ],
+  "accountNonExpired" : true,
+  "accountNonLocked" : true,
+  "credentialsNonExpired" : true,
+  "username" : "jane@test.com",
+  "enabled" : true
+} ]
+----

src/asciidoc/users/me/curl-request.adoc

@@ -0,0 +1,5 @@
+[source,bash]
+----
+$ curl 'http://localhost:8080/users/me' -i -X GET \
+    -H 'Accept: application/json'
+----