From eb46c33f1f2c56eaf2a21cf2f453fb230ef7e2e0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 26 Nov 2025 11:43:21 +0000 Subject: [PATCH 1/3] Initial plan From c98db4c34f39f3741050f23935bc9dfd72cd4d07 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 26 Nov 2025 11:46:47 +0000 Subject: [PATCH 2/3] Expand README with comprehensive repository and GitHub Actions documentation Co-authored-by: kridah <10164781+kridah@users.noreply.github.com> --- README.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 158 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5969fa1..9eaf452 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,160 @@ -Official documentation for PowerOffice API +# PowerOffice Go API Documentation [![Azure Static Web Apps CI/CD](https://github.com/PowerOffice/go-api-documentation/actions/workflows/azure-static-web-apps-gray-stone-017611203.yml/badge.svg)](https://github.com/PowerOffice/go-api-documentation/actions/workflows/azure-static-web-apps-gray-stone-017611203.yml) + +## About This Repository + +This is an **internal repository** for PowerOffice that hosts the official documentation for the PowerOffice Go API. The repository contains a React-based web application that uses Swagger UI to display and interact with the PowerOffice Go API documentation. + +### Purpose + +The main purpose of this repository is to: +- Provide interactive API documentation for PowerOffice Go API +- Host OpenAPI/Swagger specifications for the API +- Deploy the documentation automatically to Azure Static Web Apps +- Maintain version-controlled API documentation accessible to internal teams and partners + +### Technology Stack + +- **Frontend Framework**: React 18 with Vite +- **API Documentation**: Swagger UI React +- **Build Tool**: Vite +- **Deployment**: Azure Static Web Apps +- **CI/CD**: GitHub Actions + +## Repository Structure + +``` +. +├── .github/workflows/ # GitHub Actions workflows +├── src/ # React application source code +├── openapi/ # OpenAPI/Swagger specification files +│ ├── swagger.json # Main OpenAPI specification +│ └── SimplifySchemaNames.cjs # Script to simplify .NET type names +├── docs/ # Additional documentation assets +├── index.html # Main HTML entry point +├── package.json # Node.js dependencies and scripts +└── vite.config.js # Vite configuration +``` + +## How the GitHub Actions Workflow Works + +The repository uses GitHub Actions for automated building and deployment to Azure Static Web Apps. The workflow is defined in `.github/workflows/azure-static-web-apps-gray-stone-017611203.yml`. + +### Workflow Triggers + +The CI/CD pipeline is triggered on: +- **Push events** to the following branches: + - `main` (production) + - `dev` (development) + - `staging` (staging environment) +- **Pull request events** (opened, synchronize, reopened, closed) targeting the `main` branch + +### Build and Deploy Process + +The workflow consists of two main jobs: + +#### 1. Build and Deploy Job + +This job runs when code is pushed or a pull request is opened/updated: + +1. **Checkout Code**: Retrieves the repository code including submodules +2. **Setup Node.js**: Installs Node.js 18 with npm caching for faster builds +3. **Simplify Schema Names**: Runs a preprocessing script (`SimplifySchemaNames.cjs`) that: + - Processes the `swagger.json` file + - Simplifies verbose .NET type names in the OpenAPI schemas + - Removes unnecessary namespace and assembly information + - Makes the API documentation more readable +4. **Install Dependencies**: Runs `npm install` and `npm ci` to install all required packages +5. **Build Application**: Executes `npm run build` to: + - Compile the React application + - Bundle assets using Vite + - Generate production-ready static files in the `dist/` directory +6. **Deploy to Azure**: Uses the Azure Static Web Apps deployment action to: + - Upload the built application from the `dist/` directory + - Deploy to Azure Static Web Apps + - Add deployment status comments on pull requests + +#### 2. Close Pull Request Job + +This job runs when a pull request is closed: +- Removes the staging deployment associated with the pull request +- Cleans up temporary preview environments + +### Environment Variables and Secrets + +The workflow uses the following secrets (configured in GitHub repository settings): +- `AZURE_STATIC_WEB_APPS_API_TOKEN_GRAY_STONE_017611203`: Azure deployment token for authentication +- `GITHUB_TOKEN`: Automatically provided by GitHub for PR comments and integrations + +## Local Development + +### Prerequisites + +- Node.js 18 or higher +- npm (comes with Node.js) + +### Setup and Running Locally + +1. Clone the repository: + ```bash + git clone https://github.com/PowerOffice/go-api-documentation.git + cd go-api-documentation + ``` + +2. Install dependencies: + ```bash + npm install + ``` + +3. (Optional) Simplify schema names in the OpenAPI specification: + ```bash + node ./openapi/SimplifySchemaNames.cjs ./openapi/swagger.json + ``` + +4. Start the development server: + ```bash + npm run dev + ``` + +5. Open your browser to the URL shown in the terminal (typically `http://localhost:5173`) + +### Building for Production + +To create a production build: + +```bash +npm run build +``` + +The built files will be in the `dist/` directory. + +To preview the production build locally: + +```bash +npm run preview +``` + +## Deployment + +Deployments are handled automatically by GitHub Actions: +- Pushes to `main` deploy to the production environment +- Pushes to `dev` and `staging` deploy to their respective environments +- Pull requests create temporary preview deployments + +Manual deployments are not typically necessary, but if needed, ensure you have the appropriate Azure credentials configured. + +## Contributing + +This is an internal PowerOffice repository. When contributing: + +1. Create a feature branch from `dev` +2. Make your changes +3. Test locally using `npm run dev` +4. Create a pull request targeting `main` +5. The GitHub Actions workflow will automatically build and create a preview deployment +6. After review and approval, merge to deploy to production + +## Support + +For questions or issues related to this repository, please contact the PowerOffice development team. From e6bd77b5758047b323ca82e5aa9fd30b7b991393 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 26 Nov 2025 11:48:13 +0000 Subject: [PATCH 3/3] Address code review feedback: clarify npm install steps and contributing workflow Co-authored-by: kridah <10164781+kridah@users.noreply.github.com> --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9eaf452..9f5b27b 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ This job runs when code is pushed or a pull request is opened/updated: - Simplifies verbose .NET type names in the OpenAPI schemas - Removes unnecessary namespace and assembly information - Makes the API documentation more readable -4. **Install Dependencies**: Runs `npm install` and `npm ci` to install all required packages +4. **Install Dependencies**: Runs both `npm install` and `npm ci` sequentially to ensure all required packages are installed correctly 5. **Build Application**: Executes `npm run build` to: - Compile the React application - Bundle assets using Vite @@ -148,12 +148,14 @@ Manual deployments are not typically necessary, but if needed, ensure you have t This is an internal PowerOffice repository. When contributing: -1. Create a feature branch from `dev` +1. Create a feature branch from `main` 2. Make your changes 3. Test locally using `npm run dev` 4. Create a pull request targeting `main` 5. The GitHub Actions workflow will automatically build and create a preview deployment -6. After review and approval, merge to deploy to production +6. After review and approval, merge to `main` to deploy to production + +Note: Direct pushes to `dev` and `staging` branches will also trigger deployments to their respective environments. ## Support