added openapi definition

api.go

@@ -39,8 +39,8 @@ type ThinPackage struct {
 
 type PackageResponse struct {
 	Packages []*ThinPackage `json:"packages"`
-	Results  int            `json:"results"`
+	Total    int            `json:"total"`
-	Page     int            `json:"page"`
+	Offset   int            `json:"page"`
 	Limit    int            `json:"limit"`
 }
 
@@ -100,7 +100,7 @@ func GetPackages(w http.ResponseWriter, r *http.Request) {
 	pkgbase := r.URL.Query().Get("pkgbase")
 	status := r.URL.Query().Get("status")
 
-	page, err := strconv.Atoi(r.URL.Query().Get("page"))
+	offset, err := strconv.Atoi(r.URL.Query().Get("offset"))
 	if err != nil {
 		log.Warningf("error parsing page: %v", err)
 		render.Status(r, http.StatusInternalServerError)
@@ -131,7 +131,7 @@ func GetPackages(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	rPackages, err := db.DBPackage.Query().Where(constraints...).Limit(limit).Offset(limit * page).All(ctx)
+	rPackages, err := db.DBPackage.Query().Where(constraints...).Limit(limit).Offset(offset).All(ctx)
 	if err != nil {
 		log.Warningf("error getting packages from db: %v", err)
 		render.Status(r, http.StatusInternalServerError)
@@ -162,9 +162,9 @@ func GetPackages(w http.ResponseWriter, r *http.Request) {
 
 		resp.Packages = append(resp.Packages, nPkg)
 	}
-	resp.Page = page
+	resp.Offset = offset
 	resp.Limit = limit
-	resp.Results = nPkgs
+	resp.Total = nPkgs
 
 	render.Status(r, http.StatusOK)
 	render.JSON(w, r, resp)

openapi_alhp.yaml

@@ -0,0 +1,189 @@
+openapi: 3.1.0
+info:
+  title: ALHP API
+  description: |-
+    ALHP API used to retrieve information about packages and general statistics.
+
+    Some useful links:
+    - [ALHP Git](https://somegit.dev/ALHP/ALHP.GO)
+    - [ALHP Web Git](https://somegit.dev/ALHP/alhp-web)
+
+  license:
+    name: GPL3
+    url: https://somegit.dev/ALHP/alhp-web/src/branch/main/LICENSE
+  version: 1.0.0
+servers:
+  - url: https://api.alhp.dev
+tags:
+  - name: package
+    description: Everything about packages
+  - name: general
+    description: General information related to overall project status
+paths:
+  /packages:
+    get:
+      tags:
+        - package
+      summary: Get information about packages
+      description: Retrieve packages with or without filtering
+      operationId: getPackages
+      parameters:
+        - name: status
+          in: query
+          description: Status value to filter for
+          required: false
+          schema:
+            type: string
+            enum:
+              - latest
+              - failed
+              - build
+              - skipped
+              - delayed
+              - building
+              - signing
+              - unknown
+        - name: pkgbase
+          in: query
+          description: Pkgbase value to filter for
+          required: false
+          schema:
+            type: string
+        - name: offset
+          in: query
+          description: How many entries to skip
+          required: true
+          schema:
+            type: number
+        - name: limit
+          in: query
+          description: How many entries to return at max
+          required: true
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Successful retrieveal
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: 
+                  packages:
+                    type: array
+                    items: 
+                      $ref: '#/components/schemas/Package'
+                  total:
+                    type: integer
+                    format: int64
+                  offset:
+                    type: integer
+                    format: int64
+                  limit:
+                    type: integer
+                    format: int64
+        '404':
+          description: No packages found matching filters
+        '500':
+          description: Internal error
+  /stats:
+    get:
+      tags:
+        - general
+      summary: Get general package stats
+      operationId: getStats
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Stats'
+        '500':
+          description: Internal error
+  
+components:
+  schemas:
+    Package:
+      type: object
+      properties:
+        pkgbase:
+          type: string
+          examples: ["linux-zen"]
+        split_packages:
+          type: array
+          items:
+            type: string
+          examples: ["linux-zen", "linux-zen-headers", "linux-zen-docs"]
+        status:
+          type: string
+          examples: [latest]
+          enum:
+              - latest
+              - failed
+              - build
+              - skipped
+              - delayed
+              - building
+              - signing
+              - unknown
+        skip_reason:
+          type: string
+          examples: ["blacklisted"]
+        lto:
+          type: string
+          examples: [enabled]
+          enum:
+              - enabled
+              - unknown
+              - disabled
+              - auto_disabled
+        debug_symbols:
+          type: string
+          examples: [available]
+          enum:
+              - available
+              - unknown
+              - not_available
+        arch_version:
+          description: Version alhp compares to from official Archlinux repositories.
+          type: string
+          examples: ["1.3.4-2"]
+        repo_version:
+          description: Version alhp currently offers in its repositories. Can be missing/empty.
+          type: string
+          examples: ["1.3.4-2.1"]
+        build_date:
+          description: When the package was build, formatted after RFC1123
+          type: string
+          examples: ["Fri, 15 Dec 2023 03:43:11 UTC"]
+        peak_mem:
+          description: Peak memory the package used while building. Is formatted in a human readable format.
+
+    Stats:
+      type: object
+      properties:
+        failed:
+          type: integer
+          format: int64
+        skipped:
+          type: integer
+          format: int64
+        latest:
+          type: integer
+          format: int64
+        queued:
+          type: integer
+          format: int64
+        lto:
+          type: object
+          properties: 
+            enabled:
+              type: integer
+              format: int64
+            disabled:
+              type: integer
+              format: int64
+            unknown:
+              type: integer
+              format: int64