Merge pull request #67 from MathieuSoysal/40-add-open-api-schema

40 add OpenAPI documentation

.github/workflows/OpenApi.yml

@@ -0,0 +1,31 @@
+on:
+    push:
+      branches: ['master']
+      paths: ['openapi.yml']
+    workflow_dispatch:
+
+jobs:
+    build:
+        runs-on: ubuntu-latest
+        steps:
+        - name: Checkout
+          uses: actions/checkout@v4
+        - name: Convert yml to json
+          run: |
+            npm install -g @apidevtools/swagger-cli
+            swagger-cli bundle openapi.yml -t json -o openapi.json
+        - name: Generate Swagger UI
+          uses: Legion2/swagger-ui-action@v1
+          with:
+            output: swagger-ui
+            spec-file: openapi.json
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        - name: Deploy to Github Pages
+          uses: JamesIves/github-pages-deploy-action@v4.4.3
+          with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+            clean: false
+            branch: api
+            folder: swagger-ui
+            target-folder: docs
+

openapi.yml

@@ -0,0 +1,241 @@
+openapi: 3.1.0
+info:
+  title: CROUS Assistant | Residence - OpenAPI 3.1
+  description: >-
+    This is a sample API to expose the residences of the CROUS. 
+
+
+    Some useful links:
+
+    - [CROUS Assistant
+    Collector](https://github.com/MathieuSoysal/CROUS-assistant-Collector)
+  termsOfService: http://swagger.io/terms/
+  contact:
+    email: Mathieu.soysal@outlook.fr
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  version: 2.0.0
+servers:
+  - url: https://mathieusoysal.github.io/CROUS-assistant-Collector/v2
+tags:
+  - name: residence
+    description: Access to informations of each CROUS Residence
+  - name: available-residences-id
+    description: Access to available residences id to a specific date
+paths:
+  /residences:
+    get:
+      tags:
+        - residence
+      summary: Get all residence
+      description: To get all residence available residence and not available residence.
+      operationId: getAllResidence
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Residence'
+  /hash-residences:
+    get:
+      tags:
+        - residence
+      summary: Get hash code of all residences file
+      description: This hash is usefull if we know if new residence has been added
+      operationId: getHashResidences
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/text:
+              example: ssq4d864sqd86qs4
+  /available-residences-id/{date}/{hour}:
+    get:
+      tags:
+        - available-residences-id
+      summary: Get available residences id
+      description: >-
+        Returns a list of residence ids that was available for a specific date
+        time.
+      operationId: getAvailableResidenceIdsForHour
+      parameters:
+        - name: date
+          in: path
+          description: Date to get available residence ids
+          required: true
+          schema:
+            type: string
+            format: yyyy-mm-dd
+        - name: hour
+          in: path
+          description: Hour to get available residence ids
+          required: true
+          schema:
+            type: string
+            format: hh
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: integer
+  /available-residences-id/{date}/sum-up:
+    get:
+      tags:
+        - available-residences-id
+      summary: Updates a pet in the store with form data
+      description: ''
+      operationId: updatePetWithForm
+      parameters:
+        - name: date
+          in: path
+          description: Date to get available residence ids
+          required: true
+          schema:
+            type: string
+            format: yyyy-mm-dd
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: integer
+components:
+  schemas:
+    Residence:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int32
+        label:
+          type: string
+        address:
+          $ref: '#/components/schemas/Address'
+        bedCount:
+          type: integer
+          format: int32
+        bedKind:
+          type: string
+        bedroomCount:
+          type: integer
+          format: int32
+        roomCount:
+          type: integer
+          format: int32
+        inUnavailabilityPeriod:
+          type: boolean
+        description:
+          type: string
+          format: nullable
+        available:
+          type: boolean
+        highDemand:
+          type: boolean
+        lowStock:
+          type: boolean
+        equipements:
+          type: array
+          items:
+            $ref: '#/components/schemas/Equipement'
+        areaMin:
+          type: integer
+          format: int32
+        areaMax:
+          type: integer
+          format: int32
+        occupationMods:
+          type: array
+          items:
+            $ref: '#/components/schemas/OccupationMode'
+        transports:
+          type: array
+          items:
+            $ref: '#/components/schemas/Transport'
+    Address:
+      type: object
+      properties:
+        fullAddress:
+          type: string
+        street:
+          type: string
+        city:
+          type: string
+        zipCode:
+          type: string
+        location:
+          $ref: '#/components/schemas/Location'
+    Location:
+      type: object
+      properties:
+        latitude:
+          type: number
+        longitude:
+          type: number
+    Equipement:
+      type: string
+      enum:
+        - WC
+        - FRIDGE
+        - SHOWER
+        - SINK_AND_HOB
+        - LIVING_ROOM
+        - BALCONY
+        - MICROWAVE
+        - DUPLEX
+        - NONE
+        - UNKNOWN
+    OccupationMode:
+      type: object
+      properties:
+        occupationKind:
+          type: string
+        rentMin:
+          type: integer
+          format: int32
+        rentMax:
+          type: integer
+          format: int32
+    Transport:
+      type: object
+      properties:
+        kind:
+          $ref: '#/components/schemas/TransportKind'
+        description:
+          type: string
+        distance:
+          type: integer
+          format: int32
+        unitOfMeasure:
+          $ref: '#/components/schemas/TransportUnitOfMeasure'
+    TransportKind:
+      type: string
+      enum:
+        - PAYING_URBAN_PARKING
+        - FREE_URBAN_PARKING
+        - BUS
+        - TRAMWAY
+        - PRIVATE_PARKING
+        - TRAIN
+        - BIKE
+        - RER
+        - METRO
+        - NONE
+        - UNKNOWN
+    TransportUnitOfMeasure:
+      type: string
+      enum:
+        - METRE
+        - ON_FOOT
+        - NONE
+        - UNKNOWN