Docs/swagger

app/controllers/auth_controller.ts

@@ -9,8 +9,13 @@ dotenv.config()
 
 export default class AuthController {
   /**
-   * Register a new user using email and password.
-   * @returns HTTP status code + message
+   * @register
+   * @operationId register
+   * @description Register a new user with email, password, first name and last name
+   * @requestBody { "email" : "mariorossi@mail.com", "password" : "Password123", "firstName" : "Mario", "lastName" : "Rossi" }
+   * @responseBody 201 - { "message" : "Utente registrato correttamente" }
+   * @responseBody 400 - { "message" : "L'utente esiste già" }
+   * @responseBody 500 - { "message" : "Errore durante la registrazione" }
    */
   public async register({ request, response }: { request: any; response: any }) {
     const { email, password, firstName, lastName } = request.body()
@@ -34,8 +39,14 @@ export default class AuthController {
     }
   }
   /**
-   * Login a user using email and password. If the user exists and the password is correct, a JWT token is generated.
-   * @returns HTTP status code + message + JWT token
+   * @login
+   * @opetarionId login
+   * @description Login a user with email and password and set a JWT token in a cookie
+   * @requestBody { "email" : "mariorossi@mail.com", "password" : "Password123" }
+   * @responseBody 200 - { "message" : "Login effettuato con successo", "user" : { "_id" : "string", "email" : "string", "firstName" : "string", "lastName" : "string" } }
+   * @responseBody 400 - { "message" : "Credenziali invalide" }
+   * @responseBody 500 - { "message" : "Errore durante il login" }
+   * @cookie token - JWT token
    */
   public async login({ request, response }: { request: any; response: any }) {
     const { email, password } = request.body()
@@ -112,7 +123,13 @@ export default class AuthController {
       return response.status(500).json({ message: "Errore durante l'aggiornamento del token" })
     }
   }
-
+  /**
+   * @logout
+   * @operationId logout
+   * @description Logout a user and clear the JWT token from the cookie
+   * @responseBody 200 - { "message" : "Logout effettuato con successo" }
+   * @responseBody 500 - { "message" : "Errore durante il logout" }
+   */
   public async logout({ response }: { response: any }) {
     try {
       await response.clearCookie('token')

app/controllers/construction_sites_controller.ts

@@ -7,8 +7,10 @@ import { cuid } from '@adonisjs/core/helpers'
 
 export default class ConstructionSitesController {
   /**
-   * Main method for listing all construction sites.
-   * @returns list of all construction sites
+   * @index
+   * @operationId getAllConstructionSites
+   * @description Get all construction sites and the user's subscriptions if authenticated
+   * @responseBody 200 - { "constructionSites" : [ { "_id" : "67aa43801c22906f341e0880", "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image_path" : "cantiere.png", "is_subscribed" : "true" } ] }
    */
   async index({ request, response }: HttpContext) {
     const user = request.user
@@ -35,9 +37,11 @@ export default class ConstructionSitesController {
   }
 
   /**
-   * Method for showing a specific construction site.
-   * @param params: id of the construction site
-   * @returns list with the construction site with the given id
+   * @show
+   * @operationId getConstructionSites
+   * @description Get construction sites by query and the user's subscriptions if authenticated
+   * @requestParam query - string - Query to search for in the street and name fields
+   * @responseBody 200 - { "constructionSites" : [ { "_id" : "67aa43801c22906f341e0880", "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image_path" : "cantiere.png", "is_subscribed" : "true" } ] }
    */
   async show({ request, params, response }: HttpContext) {
     const user = request.user
@@ -69,9 +73,13 @@ export default class ConstructionSitesController {
   }
 
   /**
-   * Method for creating a new construction site.
-   * @param request: construction site data. List can be found in app/models/construction_site_model.ts
-   * @returns the created construction site
+   * @store
+   * @operationId createConstructionSite
+   * @description Create a new construction site
+   * @requestBody { "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image" : "cantiere.png" }
+   * @responseBody 201 - { "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image_path" : "cantiere.png" }
+   * @responseBody 400 - { "message" : "Errore nell'inserimento del cantiere" }
+   * @responseBody 500 - { "message" : "Errore nell'inserimento del cantiere" }
    */
   async store({ request, response }: HttpContext) {
     const constructionSite = new ConstructionSite(request.all())
@@ -99,9 +107,13 @@ export default class ConstructionSitesController {
   }
 
   /**
-   * Method for updating an existing construction site.
-   * @param params: id of the construction site, request: construction site data to update
-   * @returns the updated construction site
+   * @update
+   * @operationId updateConstructionSite
+   * @description Update a construction site by ID
+   * @requestBody { "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image" : "cantiere.png" }
+   * @requestParam id - string - ID of the construction site
+   * @responseBody 200 - { "name" : "Cantiere", "street" : "Via del Brennero", "description" : "Costruzione di un nuovo cantiere", "impacts_road" : "true", "image_path" : "cantiere.png" }
+   * @responseBody 404 - { "message" : "Cantiere non trovato" }
    */
   async update({ params, request, response }: HttpContext) {
     try {
@@ -123,9 +135,12 @@ export default class ConstructionSitesController {
   }
 
   /**
-   * Method for deleting a construction site.
-   * @param params: id of the construction site
-   * @returns the deleted construction site
+   * @destroy
+   * @operationId deleteConstructionSite
+   * @description Delete a construction site by ID
+   * @requestParam id - string - ID of the construction site
+   * @responseBody 204 - { "message" : "Cantiere eliminato con successo" }
+   * @responseBody 404 - { "message" : "Cantiere non trovato" }
    */
   async destroy({ params, response }: HttpContext) {
     try {

app/controllers/notifications_controller.ts

@@ -1,6 +1,14 @@
 import type { HttpContext } from '@adonisjs/core/http'
 import Notification from '../models/notification_model.js'
 
+/**
+ * @getNotifications
+ * @operationId getNotifications
+ * @description Get all unread notifications for the authenticated user
+ * @responseBody 200 - { "notifications" : [ { "_id" : "67aa43801c22906f341e0880", "user_id" : "67aa43801c22906f341e0880", "message" : "Nuova notifica", "read" : "false" } ] }
+ * @responseBody 400 - { "message" : "Errore durante il recupero delle notifiche" }
+ * @responseBody 401 - { "message" : "Non autorizzato" }
+ */
 export default class NotificationsController {
   public async getNotifications({ request, response }: HttpContext) {
     try {
@@ -12,6 +20,14 @@ export default class NotificationsController {
     }
   }
 
+  /**
+   * @markAsRead
+   * @operationId markAsRead
+   * @description Mark all notifications as read for the authenticated user
+   * @responseBody 200 - { "message" : "Notifications marked as read" }
+   * @responseBody 400 - { "message" : "Errore durante la marcatura delle notifiche come lette" }
+   * @responseBody 401 - { "message" : "Non autorizzato" }
+   */
   public async markAsRead({ request, response }: HttpContext) {
     try {
       let user = request.user

app/controllers/subscriptions_controller.ts

@@ -2,6 +2,15 @@ import type { HttpContext } from '@adonisjs/core/http'
 import Subscription from '../models/subscription_model.js'
 
 export default class SubscriptionsController {
+  /**
+   * @subscribe
+   * @operationId subscribe
+   * @description Subscribe the authenticated user to a construction site
+   * @requestBody { "construction_site_id" : "67aa43801c22906f341e0880" }
+   * @responseBody 201 - { "user_id" : "67aa43801c22906f341e0880", "construction_site_id" : "67aa438
+   * @responseBody 400 - { "message" : "Dati mancanti: user_id o construction_site_id null" }
+   * @responseBody 409 - { "message" : "L'utente è già iscritto a questo cantiere" }
+   */
   public async subscribe({ request, response }: HttpContext) {
     const user = request.user
     const constructionSiteId = request.body().construction_site_id
@@ -25,7 +34,14 @@ export default class SubscriptionsController {
     return response.created(subscription)
   }
 
-  // ROTUE IS DELETE NOT POST
+  /**
+   * @unsubscribe
+   * @operationId unsubscribe
+   * @description Unsubscribe the authenticated user from a construction site
+   * @requestParam id - string - Construction site ID
+   * @response 204
+   * @response 404
+   */
   public async unsubscribe({ params, request, response }: HttpContext) {
     let user = request.user
     let subscription = await Subscription.findOne({

config/swagger.ts

@@ -0,0 +1,28 @@
+// for AdonisJS v6
+import path from 'node:path'
+import url from 'node:url'
+// ---
+
+export default {
+  // path: __dirname + '/../', for AdonisJS v5
+  path: path.dirname(url.fileURLToPath(import.meta.url)) + '/../', // for AdonisJS v6
+  title: 'Citium',
+  version: '1.0.0', // use info instead
+  description: 'Citium API documentation',
+  tagIndex: 2,
+  info: {
+    title: 'Citium',
+    version: '1.0.0',
+    description: 'Citium API documentation',
+  },
+  snakeCase: true,
+
+  debug: false, // set to true, to get some useful debug output
+  ignore: ['/swagger', '/docs'],
+  preferredPutPatch: 'PUT', // if PUT/PATCH are provided for the same route, prefer PUT
+  common: {
+    parameters: {}, // OpenAPI conform parameters that are commonly used
+    headers: {}, // OpenAPI conform headers that are commonly used
+  },
+  showFullPath: false, // the path displayed after endpoint summary
+}