docs: add swagger spec

.gitignore

@@ -7,4 +7,5 @@ report.json
 dist
 coverage
 node_modules
-uploads
+uploads
+src/swagger/swagger.json

README.md

@@ -83,6 +83,8 @@ export STORAGE_TYPE=local
 yarn dev
 ```
 
+The Swagger UI is available at `http://localhost:3333/api-docs`.
+
 ### Google Cloud Storage
 
 For production environments,
@@ -104,6 +106,8 @@ yarn build
 yarn start
 ```
 
+The Swagger UI is available at `http://localhost:3333/api-docs`.
+
 ## Cryptography
 
 The cryptography service uses the following algorithms:
@@ -167,6 +171,14 @@ The cryptography service uses the following algorithms:
     }
     ```
 
+## API versions and Source Code versions
+
+The following table lists the API versions and the corresponding source code versions:
+
+| API Version | Source Code Version From                                      | Source Code Version To                                        |
+| ----------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
+| v1.0.0      | [next](https://github.com/uncefact/project-identity-resolver) | [next](https://github.com/uncefact/project-identity-resolver) |
+
 ## Docker
 
 To run the storage service using Docker:

package.json

@@ -1,8 +1,10 @@
 {
     "name": "storage_service_traceability",
+    "version": "1.0.0",
     "scripts": {
-        "build": "npx webpack --mode production --config webpack.config.cjs",
-        "dev": "yarn npm-run-all --parallel  watch:build watch:server",
+        "bundle-swagger": "redocly bundle src/swagger/index.json --output src/swagger/swagger.json",
+        "build": "yarn bundle-swagger && npx webpack --mode production --config webpack.config.cjs",
+        "dev": "yarn npm-run-all --parallel bundle-swagger watch:build watch:server",
         "lint": "eslint",
         "postinstall": "husky",
         "start": "node dist/index.js",
@@ -18,22 +20,26 @@
         "dotenv": "^16.4.1",
         "express": "^4.18.2",
         "lodash": "^4.17.21",
+        "swagger-ui-express": "^5.0.1",
         "uuid": "^10.0.0"
     },
     "devDependencies": {
         "@babel/core": "^7.23.9",
         "@babel/preset-env": "^7.23.9",
         "@jest-mock/express": "^2.0.2",
+        "@redocly/cli": "^1.25.11",
         "@types/cors": "^2.8.17",
         "@types/express": "^4.17.21",
         "@types/jest": "^29.5.12",
         "@types/lodash": "^4.14.202",
         "@types/node": "^20.11.16",
+        "@types/swagger-ui-express": "^4.1.7",
         "@types/uuid": "^10.0.0",
         "@typescript-eslint/eslint-plugin": "^6.4.0",
         "@typescript-eslint/parser": "^6.21.0",
         "babel-jest": "^29.7.0",
         "babel-loader": "^9.1.3",
+        "copy-webpack-plugin": "^12.0.2",
         "eslint": "^8.0.1",
         "husky": "^9.0.10",
         "jest": "^29.7.0",

src/app.ts

@@ -3,12 +3,17 @@ dotenv.config();
 
 import cors from 'cors';
 import express from 'express';
+import swaggerUi from 'swagger-ui-express';
 import bodyParser from 'body-parser';
 import { API_VERSION } from './config';
 import { router } from './routes';
+import swaggerDocument from './swagger/swagger.json';
+import { updateSwagger } from './swagger/helpers';
 
 export const app = express();
 
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(updateSwagger(swaggerDocument)));
+
 app.use(cors());
 
 // Update limit to 50mb to allow for large data uploads

src/config.ts

@@ -1,6 +1,8 @@
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
-export const API_VERSION = process.env.API_VERSION || 'v1';
+
+// The API_VERSION is set manually, it should be updated when having change impact on the API.
+export const API_VERSION = 'v1.0.0';
 export const PROTOCOL = process.env.PROTOCOL || 'http';
 export const DOMAIN = process.env.DOMAIN || 'localhost';
 export const PORT = process.env.PORT || 3333;

src/server.ts

@@ -3,4 +3,5 @@ import { API_VERSION, DOMAIN, PORT, PROTOCOL } from './config';
 
 app.listen(PORT, () => {
     console.log(`Server is running: ${PROTOCOL}://${DOMAIN}:${PORT}/${API_VERSION} 🚀`);
+    console.log(`API documentation: ${PROTOCOL}://${DOMAIN}:${PORT}/api-docs 📚`);
 });

src/swagger/components/examples.json

@@ -0,0 +1,53 @@
+{
+    "components": {
+        "examples": {
+            "ExampleRequest1": {
+                "summary": "Verifiable Credential",
+                "value": {
+                    "bucket": "verifiable-credentials",
+                    "id": "123e4567-e89b-12d3-a456-426614174000",
+                    "data": {
+                        "@context": [
+                            "https://www.w3.org/ns/credentials/v2",
+                            "https://www.w3.org/ns/credentials/examples/v2"
+                        ],
+                        "id": "http://example.gov/credentials/3732",
+                        "type": ["VerifiableCredential", "ExampleDegreeCredential"],
+                        "issuer": "did:example:6fb1f712ebe12c27cc26eebfe11",
+                        "validFrom": "2010-01-01T19:23:24Z",
+                        "credentialSubject": {
+                            "id": "https://subject.example/subject/3921",
+                            "degree": {
+                                "type": "ExampleBachelorDegree",
+                                "name": "Bachelor of Science and Arts"
+                            }
+                        },
+                        "proof": {
+                            "type": "DataIntegrityProof",
+                            "cryptosuite": "eddsa-rdfc-2022",
+                            "created": "2021-11-13T18:19:39Z",
+                            "verificationMethod": "https://university.example/issuers/14#key-1",
+                            "proofPurpose": "assertionMethod",
+                            "proofValue": "z58DAdFfa9SkqZMVPxAQp...jQCrfFPP2oumHKtz"
+                        }
+                    }
+                }
+            },
+            "ExampleRequest2": {
+                "summary": "Enveloped Verifiable Credential",
+                "value": {
+                    "bucket": "verifiable-credentials",
+                    "id": "123e4567-e89b-12d3-a456-426614174001",
+                    "data": {
+                        "@context": [
+                            "https://www.w3.org/ns/credentials/v2",
+                            "https://www.w3.org/ns/credentials/examples/v2"
+                        ],
+                        "id": "data:application/vc+jwt,eyJraWQiOiJFeEhrQk1XOWZtYmt2VjI2Nm1ScHVQMnNVWV9OX0VXSU4xbGFwVXpPOHJvIiwiYWxnIjoiRVMyNTYifQ .eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwOi8vdW5pdmVyc2l0eS5leGFtcGxlL2NyZWRlbnRpYWxzLzE4NzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRXhhbXBsZUFsdW1uaUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly91bml2ZXJzaXR5LmV4YW1wbGUvaXNzdWVycy81NjUwNDkiLCJ2YWxpZEZyb20iOiIyMDEwLTAxLTAxVDE5OjIzOjI0WiIsImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2V4YW1wbGUub3JnL2V4YW1wbGVzL2RlZ3JlZS5qc29uIiwidHlwZSI6Ikpzb25TY2hlbWEifSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZToxMjMiLCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFNjaWVuY2UgYW5kIEFydHMifX19 .vLtI6zKqEquVX-2RPhGyvHzQ9xdKOdFGRoFaEnG-UhQMGG7OGPi0WAoKPrj8OiT-LDcLMAUNKPncwPc8B-lqKg",
+                        "type": "EnvelopedVerifiableCredential"
+                    }
+                }
+            }
+        }
+    }
+}

src/swagger/components/responses.json

@@ -0,0 +1,54 @@
+{
+    "components": {
+        "responses": {
+            "400": {
+                "description": "The request is invalid.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "message": {
+                                    "type": "string",
+                                    "example": "Bucket is required. Please provide a bucket name."
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "409": {
+                "description": "The credential already exists.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "message": {
+                                    "type": "string",
+                                    "example": "A credential with the provided ID already exists in the specified bucket."
+                                }
+                            }
+                        }
+                    }
+                }
+            },
+            "500": {
+                "description": "An error occurred while storing the credential.",
+                "content": {
+                    "application/json": {
+                        "schema": {
+                            "type": "object",
+                            "properties": {
+                                "message": {
+                                    "type": "string",
+                                    "example": "An unexpected error occurred while storing the credential."
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

src/swagger/components/schemas.json

@@ -0,0 +1,35 @@
+{
+    "components": {
+        "schemas": {
+            "Credential": {
+                "type": "object",
+                "properties": {
+                    "bucket": {
+                        "type": "string",
+                        "example": "verifiable-credentials"
+                    },
+                    "data": {
+                        "type": "object",
+                        "properties": {
+                            "field1": {
+                                "type": "string",
+                                "example": "value1"
+                            },
+                            "field2": {
+                                "type": "string",
+                                "example": "value2"
+                            }
+                        }
+                    },
+                    "id": {
+                        "type": "string",
+                        "format": "uuid",
+                        "example": "123e4567-e89b-12d3-a456-426614174000",
+                        "description": "Optional"
+                    }
+                },
+                "required": ["bucket", "data"]
+            }
+        }
+    }
+}

src/swagger/helpers.ts

@@ -0,0 +1,13 @@
+import { PROTOCOL, DOMAIN, PORT, API_VERSION } from '../config';
+
+export const updateSwagger = (swaggerJson: Record<string, any>) => {
+    const swagger = { ...swaggerJson };
+    swagger.info = swagger.info || {};
+    swagger.info.version = API_VERSION;
+    swagger.servers = [
+        {
+            url: `${PROTOCOL}://${DOMAIN}:${PORT}/${API_VERSION}`,
+        },
+    ];
+    return swagger;
+};

src/swagger/index.json

@@ -0,0 +1,18 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Storage Service API"
+    },
+    "servers": [],
+    "paths": {
+        "$ref": "./paths.json#/paths"
+    },
+    "components": {
+        "schemas": {
+            "$ref": "./components/schemas.json#/components/schemas"
+        },
+        "examples": {
+            "$ref": "./components/examples.json#/components/examples"
+        }
+    }
+}