diff --git a/.gitignore b/.gitignore index d1d1409..7ff5101 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ build # ide .idea +.vscode # For MacOs .DS_Store \ No newline at end of file diff --git a/app/build.gradle b/app/build.gradle index b865539..b811536 100644 --- a/app/build.gradle +++ b/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') +} diff --git a/app/src/docs/asciidoc/main.adoc b/app/src/docs/asciidoc/main.adoc new file mode 100644 index 0000000..51d687d --- /dev/null +++ b/app/src/docs/asciidoc/main.adoc @@ -0,0 +1,107 @@ += ```template-java-API``` Documentation +Damien Jaime + +: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, <>. + +[bibliography] +== References + +- [[[ej3,1]]] Joshua Bloch. Effective Java, Third Edition. Pearson Education. 2018. \ No newline at end of file diff --git a/app/src/docs/asciidoc/models/commons.style b/app/src/docs/asciidoc/models/commons.style new file mode 100644 index 0000000..d79df53 --- /dev/null +++ b/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<> { + 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 +} \ No newline at end of file diff --git a/app/src/docs/asciidoc/models/diagram.puml b/app/src/docs/asciidoc/models/diagram.puml new file mode 100644 index 0000000..df8bd6d --- /dev/null +++ b/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 diff --git a/app/src/main/java/fr/parisnanterre/controllers/HelloController.java b/app/src/main/java/fr/parisnanterre/controllers/HelloController.java index bb04edd..8576cac 100644 --- a/app/src/main/java/fr/parisnanterre/controllers/HelloController.java +++ b/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(); } } diff --git a/app/src/main/java/fr/parisnanterre/models/HelloModel.java b/app/src/main/java/fr/parisnanterre/models/HelloModel.java new file mode 100644 index 0000000..64547b4 --- /dev/null +++ b/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"; + } +}