Asciidoc: Merge branch 'develop', Close #13 & #14

.gitignore

@@ -6,6 +6,7 @@ build
 
 # ide
 .idea
+.vscode
 
 # For MacOs
 .DS_Store

app/build.gradle

@@ -10,6 +10,27 @@ plugins {
     id 'application'
     id 'jacoco' // For test coverage
     id "org.sonarqube" version "4.4.1.3373" // For code quality
+    // For generate doc
+    id 'org.asciidoctor.jvm.convert' version '4.0.2'
+    id 'org.asciidoctor.jvm.pdf' version '4.0.2'
+}
+
+asciidoctor {
+    sourceDir = file('src/docs/asciidoc')
+    outputDir = file("${buildDir}/docs")
+}
+asciidoctorj {
+    requires 'rouge'
+    modules {
+        diagram.use()
+        diagram.version '1.5.16'
+    }
+    attributes 'build-gradle': file('build.gradle'),
+        'sourcedir': project.sourceSets.main.java.srcDirs[0],
+        'source-highlighter': 'rouge',
+        'rouge-style': 'github',
+        'rouge-theme': 'github'
+
 }
 
 jacoco {
@@ -47,11 +68,13 @@ repositories {
 dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-web:3.3.3'
     implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
-
+    // test
     testImplementation libs.junit
     testImplementation 'org.springframework.boot:spring-boot-starter-test:3.3.3'
 }
 
+
+
 // Apply a specific Java toolchain to ease working on different environments.
 java {
     toolchain {
@@ -63,3 +86,11 @@ application {
     // Define the main class for the application.
     mainClass = 'fr.parisnanterre.App'
 }
+
+// edit the build task to generate the asciidoc pdf too
+tasks.named('asciidoctor').configure {
+    dependsOn tasks.named('asciidoctorPdf')
+}
+tasks.named('build').configure {
+    dependsOn tasks.named('asciidoctor')
+}

app/src/docs/asciidoc/main.adoc

@@ -0,0 +1,107 @@
+= ```template-java-API``` Documentation
+Damien Jaime <djaime@parisnanterre.fr>
+
+:plantuml:
+ifndef::modelsdir[:modelsdir: models]
+
+== How to install?
+
+=== Note
+
+Tested with gradle 8.10.1 and Java 17.0.12
+
+=== If you have ```git``` on your computer
+
+Simply run:
+[source,shell]
+----
+git clone https://github.com/DaJaime/template-java-API
+----
+
+=== If you do not have ```git``` on your computer
+
+Go to https://github.com/DaJaime/template-java-API, get the zipfile and uncompress it.
+
+== How to run?
+
+Simply run:
+[source, shell]
+----
+./gradlew run
+----
+
+== What does ```template-java-project``` do?
+
+This project creates a REST API using Spring boot, with a single route returning “Hello”.
+
+Here is the class diagram.
+
+First a file included version without style:
+
+plantuml::src/docs/asciidoc/models/diagram.puml[svg]
+
+Then an inlined version with style:
+
+[plantuml, svg, config="src/docs/asciidoc/models/commons.style"]
+.App class diagram
+----
+@startuml
+
+package fr.parisnanterre {
+    class App {
+        + main(String[] args)
+    }
+
+    package controllers {
+        class HelloController {
+            + getHello() : String
+        }
+    }
+
+    package models {
+            class HelloModel {
+                + sayHello() : String
+            }
+        }
+    ' Relationships
+    App --> HelloController : "creates"
+    HelloController --> HelloModel
+}
+
+' Adding Spring Boot dependencies to highlight Spring context
+package org.springframework {
+    interface SpringApplication
+    interface RestController
+    interface GetMapping
+
+    App --> SpringApplication : "run()"
+    HelloController --> RestController
+    HelloController --> GetMapping
+}
+
+package io.swagger.v3.oas.annotations{
+    interface Operation
+    interface Tag
+
+    HelloController --> Operation
+    HelloController --> Tag
+}
+
+@enduml
+----
+Here is a part of the API source code (using ```include``` but you can also put it directly):
+
+[source,java]
+.HelloController source code
+----
+include::{sourcedir}/fr/parisnanterre/controllers/HelloController.java[indent=0]
+----
+
+== Last comments
+
+Let us end with a recommended book, <<ej3>>.
+
+[bibliography]
+== References
+
+- [[[ej3,1]]] Joshua Bloch. Effective Java, Third Edition. Pearson Education. 2018.

app/src/docs/asciidoc/models/commons.style

@@ -0,0 +1,65 @@
+'Style defined by Benjamin Benni during his PhD thesis'
+'Adapted by Sébastien Mosser for INF-5153'
+'https://github.com/ace-lectures/pattern-repository/blob/master/commons.style
+'consider giving a star to it
+
+skinparam nodesep 75
+skinparam ranksep 75
+hide empty members
+
+skinparam noteFontSize 10
+skinparam noteFontName Courier
+
+skinparam monochrome  false
+skinparam shadowing   false
+skinparam roundcorner 10
+skinparam linetype polyline
+
+skinparam class {
+    BackgroundColor GhostWhite
+    ArrowColor      Gray
+    BorderColor     Black
+    fontColor       CornFlowerBlue
+}
+
+skinparam state {
+    BackgroundColor GhostWhite
+    ArrowColor      Gray
+    BorderColor     Black
+    fontColor       CornFlowerBlue
+}
+
+skinparam object {
+    BackgroundColor GhostWhite
+    ArrowColor      Gray
+    BorderColor     Black
+}
+
+skinparam package<<Layout>> {
+  borderColor         Transparent
+  backgroundColor     Transparent
+  fontColor           Transparent
+  stereotypeFontColor Transparent
+}
+
+skinparam sequence {
+	ArrowColor                  Gray
+  LifeLineBorderColor         CornFlowerBlue
+  LifeLineBackgroundColor     GhostWhite
+	ParticipantBorderColor      CornFlowerBlue
+	ParticipantBackgroundColor  GhostWhite
+  ActorBorderColor            CornFlowerBlue
+	ActorBackgroundColor        GhostWhite
+  BoxBorderColor         CornFlowerBlue
+  BoxBackgroundColor         GhostWhite
+}
+
+skinparam stereotypeCBackgroundColor CornflowerBlue
+
+hide footbox
+hide empty members
+
+skinparam note {
+ BackgroundColor GhostWhite
+ BorderColor         CornFlowerBlue
+}

app/src/docs/asciidoc/models/diagram.puml

@@ -0,0 +1,43 @@
+@startuml
+
+package fr.parisnanterre {
+    class App {
+        + main(String[] args)
+    }
+
+    package controllers {
+        class HelloController {
+            + getHello() : String
+        }
+    }
+
+    package models {
+            class HelloModel {
+                + sayHello() : String
+            }
+        }
+    ' Relationships
+    App --> HelloController : "creates"
+    HelloController --> HelloModel
+}
+
+' Adding Spring Boot dependencies to highlight Spring context
+package org.springframework {
+    interface SpringApplication
+    interface RestController
+    interface GetMapping
+
+    App --> SpringApplication : "run()"
+    HelloController --> RestController
+    HelloController --> GetMapping
+}
+
+package io.swagger.v3.oas.annotations{
+    interface Operation
+    interface Tag
+
+    HelloController --> Operation
+    HelloController --> Tag
+}
+
+@enduml

app/src/main/java/fr/parisnanterre/controllers/HelloController.java

@@ -1,5 +1,6 @@
 package fr.parisnanterre.controllers;
 
+import fr.parisnanterre.models.HelloModel;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -15,6 +16,6 @@ public class HelloController {
             description = "This endpoint returns a simple message saying 'Hello from API'"
     )
     public String getHello() {
-        return "Hello from API";
+        return HelloModel.sayHello();
     }
 }

app/src/main/java/fr/parisnanterre/models/HelloModel.java

@@ -0,0 +1,7 @@
+package fr.parisnanterre.models;
+
+public class HelloModel {
+    public static String sayHello(){
+        return "Hello from API";
+    }
+}