PI-2374 Migrate OpenAPI yaml to annotations (#466)

Author: marcus-bcl

.github/workflows/generate-api-docs.yml

@@ -0,0 +1,33 @@
+name: Generate OpenAPI spec
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+  generate-openapi-spec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+      - uses: gradle/actions/setup-gradle@v4
+      - name: Serve dependencies
+        run: make serve-dependencies
+      - name: Start service
+        run: |
+          ./gradlew bootRun &
+          timeout 300 sh -c 'until curl -s localhost:8080/v3/api-docs; do sleep 5; done'
+        env:
+          SPRING_PROFILES_ACTIVE: local
+      - name: Fetch API docs
+        run: mkdir -p openapi && curl -f localhost:8080/v3/api-docs -o openapi/api-docs.json
+      - name: Publish API docs
+        uses: JamesIves/github-pages-deploy-action@94f3c658273cf92fb48ef99e5fbc02bd2dc642b2 # v4.6.3
+        with:
+          folder: openapi
+          target-folder: openapi

.github/workflows/generate-plantuml-diagrams.yml

@@ -13,7 +13,7 @@ jobs:
     env:
       BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Install Graphviz Dependency
         run: |
           sudo apt-get install graphviz

Makefile

@@ -2,20 +2,23 @@ authenticate-docker:
 	./scripts/authenticate_docker.sh
 
 build-dev:
-	docker-compose pull hmpps-auth
-	docker-compose build --no-cache
+	docker compose pull hmpps-auth
+	docker compose build
 
 build:
 	docker build -t hmpps-integration-api .
 
+serve-dependencies:
+	docker compose up hmpps-auth prism local-stack-aws --build -d
+
 serve: build-dev
-	docker-compose up -d
+	docker compose up -d
 
 publish:
 	./scripts/publish.sh
 
 stop:
-	docker-compose down
+	docker compose down
 
 unit-test:
 	./gradlew unitTest

README.md

@@ -88,20 +88,21 @@ minutes.
 
 ## Usage
 
-### Running the application
+### Running the application locally
 
 To run the application using IntelliJ:
 
-1. Select the `HmppsIntegrationApi` run configuration file.
-2. Click the run button.
+1. Start dependencies using `make serve-dependencies`
+2. Select the `HmppsIntegrationApi` run configuration file.
+3. Click the run button.
 
-To run the application using the command line:
+Or, to run the application using the command line:
 
 ```bash
-./gradlew bootRun
+SPRING_PROFILES_ACTIVE=local ./gradlew bootRun
 ```
 
-Then visit [http://localhost:8080](http://localhost:8080).
+Then visit [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html).
 
 #### With dependent services
 

build.gradle.kts

@@ -20,6 +20,7 @@ dependencies {
     exclude("org.springframework.security", "spring-security-crypto")
     exclude("org.springframework.security", "spring-security-web")
   }
+  implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")
   testImplementation("io.kotest:kotest-assertions-json-jvm:5.8.0")
   testImplementation("io.kotest:kotest-runner-junit5-jvm:5.8.0")
   testImplementation("io.kotest:kotest-assertions-core-jvm:5.8.0")

docs/adr/0011-openapi-revision.md

@@ -0,0 +1,29 @@
+# 0011 - Revert decision 0003 and auto-generate OpenAPI specification
+
+2024-08-16
+
+## Status
+
+Proposed
+
+## Context
+
+In [#0003](./0003-manually-manage-openapi-file.md), the team decided to manually manage the OpenAPI specification file, as opposed to generating them from code. 
+This had the benefit of allowing the team to write documentation for endpoints before they have been built.
+However, in practice this has resulted in an out-of-date specification due to code changes not being reflected.
+
+## Decision
+
+Revert decision 0003 and auto-generate OpenAPI specification using the [Springdoc OpenAPI library](https://springdoc.org).
+When the code or annotations change, the OpenAPI specification will be generated and published automatically.
+Additional documentation can be added for endpoints that have not yet been implemented, by adding a separate "draft" OpenAPI specification file.
+
+### Rationale
+* Auto-generating OpenAPI specifications from annotations in code is consistent with the wider HMPPS approach
+* Keeping documentation as close to the relevant code as possible ensures it is kept up-to-date
+* Pre-existing documentation is maintained
+* Additional documentation that doesn't correspond to code can be drafted separately
+
+## Consequences
+* The existing OpenAPI yaml file will be converted into code annotations, and will be published automatically via GitHub pages.
+* The tech-docs pages will be updated to reference the new location.