Add API Designer docs

docs/api-designer/design-apis.md

@@ -0,0 +1,65 @@
+# Design APIs using API Designer
+
+You can use API Designer to create and improve your OpenAPI 3.x specification with AI-assisted workflows and form-based editing.
+
+## Start with AI design
+
+The API Designer extension includes the `api-design` skill for specification design. Open GitHub Copilot Chat and provide a prompt to design an API. Based on your prompt intent, Copilot automatically picks and uses the skill to draft the specification.
+
+![API Design Skill](./images/api-design-skill.png)
+
+Example prompt:
+> Design an OpenAPI spec for an Orders API with CRUD operations.
+
+
+## Open the designer
+
+Open your specification file, then open API Designer (see [Getting started](./getting-started.md)). API Designer treats the file as the source of truth and writes updates back to the same file.
+
+### Work in Design view
+
+![Design view](./images/design-view.png)
+
+Use Design view to:
+
+- View API resources, operations, and reusable components in one place.
+- **Edit with AI** for intent-driven updates using natural-language prompts.
+- Use form-based editing for precise structural changes in operations and schemas.
+- Review OpenAPI specification issues (such as errors and warnings) identified by Spectral's OAS ruleset.
+
+## Edit the specification
+
+1. **Edit with AI**
+    - Describe intent in natural language and apply changes to the relevant operation or schema.
+    - Use this for larger or repetitive updates.
+
+2. **Use form-based editing**
+    - Update operations, parameters, responses, and schemas through guided forms.
+    - Use this for precise structural changes.
+    ![Form Based Editing](./images/form-based-editor.png)
+
+## Validate the specification
+
+Validation issues are problems detected in your OpenAPI specification while you edit.
+
+Design view shows validation results directly in the editor:
+
+- A **validation status bar** appears when issues are found, with clickable badges for **errors** and **warnings**.
+  ![Validation issues bar](./images/validation-issues-bar.png)
+
+- Click a badge to open **Validation Issues**, which groups findings by severity.
+- Each issue shows a **message** and its **location path** in the specification.
+- Selecting an issue opens a **details pane** with more context (including a spec snippet when line-range data is available).
+
+  ![Validation issues](./images/validation-issues.png)
+
+### Fixing from the validation panel
+
+- Use **Fix with AI** on a single issue to open Chat with issue context.
+- Use **Fix All with AI** in the active tab (errors or warnings) to iterate through all listed issues.
+- After applying changes, the panel refreshes so you can verify that issues are resolved.
+
+## Related topics
+
+- [Govern APIs using API Designer](./govern-apis.md) — report cards, findings, and fixes
+- [End-to-end tutorial](./end-to-end-tutorial.md) — full workflow from draft to fixes

docs/api-designer/end-to-end-tutorial.md

@@ -0,0 +1,111 @@
+# End-to-end tutorial
+
+Follow this guide once to understand the full API Designer workflow using one OpenAPI file.
+
+In this tutorial, you will:
+
+- Draft a spec with Copilot.
+- Refine it in API Designer.
+- Review governance reports.
+- Fix findings using Chat.
+
+## Step 1: Draft the spec with Copilot
+
+1. Open GitHub Copilot Chat with agent mode.
+2. Ask Copilot to scaffold a complete OpenAPI specification for an Orders API.
+
+Example prompt:
+
+> Design an API for Order management app
+
+3. Copilot Chat uses the `api-design` skill, may ask clarifying questions, and iterates until the specification is ready. It then writes and saves the file.
+
+Outcome: A working OpenAPI draft on workspace.
+
+Note: If Copilot prompts you to open the specification in API Designer, confirm the prompt.
+
+## Step 2: Open API Designer
+
+1. With the openapi spec file (e.g: `orders-api.yaml`) focused, open API Designer using one of these options:
+    - Copilot Chat: Confirm the prompt to open in API Designer (uses the `openInApiDesigner` tool).
+      ![Copilot Chat Open In API Designer prompt](./images/open-in-api-designer-chat.png)
+    - CodeLens: Open in API Designer.
+    - Title bar: Open in API Designer.
+    - Command Palette: API Designer: Open in API Designer.
+    - If a notification appears (“Open it in API Designer?”), choose **Open in API Designer**.
+
+Outcome: You get a structured view of paths, operations, and components.
+
+## Step 3: Edit with AI
+
+1. Stay in the designer (or use the AI entry point your build provides for "edit with AI").
+2. Prompt with scope, for example:
+
+   Click on the **Edit with AI** button in the orders GET endpoint and type:
+
+      > Add `limit` and `offset` query parameters with defaults documented in the parameter descriptions.
+
+      ![Edit with AI](./images/ai-based-editor.png)
+
+   This will open up the copilot chat in agent mode and run the prompt with the provided scope.
+
+3. Review the proposed changes and accept only what matches your API conventions.
+
+Outcome: Fast updates for larger or repetitive changes.
+
+## Step 4: Use form-based edits
+
+1. In the designer, open the Edit form for a specific operation or schema.
+2. Adjust a response code, update an operation summary/description, mark a schema field as required, or refine a parameter type and constraints.
+
+   ![Edit with Forms](./images/form-based-editor.png)
+
+Outcome: Safe and precise structural edits.
+
+## Step 5: Open a governance report and review findings
+
+1. In the designer, report cards are available for the following:
+   - WSO2 REST API AI Readiness Guidelines
+   - WSO2 REST API Design Guidelines
+   - OWASP API Security Top 10
+2. Click any report card to open the full report and review its score and issue list.
+
+![Governance Report](./images/analyze-view.png)
+
+Outcome: You can prioritize issues by impact and severity.
+
+## Step 6: Triage findings
+
+1. Quick wins: missing `operationId`, obvious response gaps, and thin descriptions.
+2. Design consistency: naming, pagination envelope, and error model alignment.
+3. Security: items that need real auth configuration or URLs.
+
+Outcome: A practical fix backlog.
+
+## Step 7: Fix with AI (Chat + `api-design` skill)
+
+1. Open **Chat** with the spec available (open editor or `@` file reference, depending on product).
+2. Ask for a bounded fix tied to the report, for example:
+
+   > Using the api-design skill: apply all **auto-fixable** findings from the current readiness report for `orders-api.yaml`. Do **not** rename paths without asking. List anything that needs manual security or deployment details.
+
+3. Open the relevant report card again and review the updated report.
+
+Outcome: Better report scores and fewer open findings.
+
+## Recap
+
+```text
+Copilot (draft YAML)
+Open in API Designer -> structured editor (overview)
+Edit with AI (scoped) + Forms (precise)
+Report cards (ready in UI) -> Spectral reports + AI readiness narrative
+Chat / api-design skill -> safe fixes + confirm breaking changes
+Open reports again -> ship or iterate
+```
+
+## See also
+
+- [API Designer getting started](./getting-started.md)
+- [Design APIs with API Designer](./design-apis.md)
+- [Govern APIs with API Designer](./govern-apis.md)

docs/api-designer/getting-started.md

@@ -0,0 +1,40 @@
+# API Designer
+
+API Designer is a Visual Studio Code extension for building and improving OpenAPI specifications. It helps you use AI to design APIs faster, assess AI readiness, and fix governance issues.
+
+## What you can do
+
+- Design APIs with **Github Copilot** using the built-in **API Design Skill**, with guided recommendations and faster fixes.
+- Design and edit OpenAPI specs visually inside VS Code with GitHub Copilot Assistance
+- Validate APIs against governance and best-practice rulesets
+- Analyze **AI readiness** and identify improvement areas
+
+## Prerequisites
+
+- Visual Studio Code (compatible with extension engine requirement `^1.100.0`).
+- GitHub Copilot (optional, recommended for AI-assisted workflows).
+
+## Quick start
+
+1. Install API Designer from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=WSO2.api-designer).
+2. Open your OpenAPI file (`.yaml` or `.json`), or create one with GitHub Copilot using the bundled `api-design` skill.
+3. Open API Designer. You can open it in any of these ways:
+
+    - CodeLens in the file: Open in API Designer
+    - Editor title bar: Open in API Designer
+    - Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`): API Designer: Open in API Designer
+    - Open-file notification (when `apiDesigner.notifyOnOpen` is enabled)
+
+    ![Options: Open in API Designer](./images/options.png)
+
+4. Use AI-assisted editing to improve operations, descriptions, and examples in your spec.
+   ![Design View](./images/design-view.png)
+
+5. Open report cards and review AI readiness and governance findings.
+   ![Governance Report](./images/analyze-view.png)
+
+## Next steps
+
+- Learn how to create and refine your specification in [Design APIs using API Designer](./design-apis.md).
+- Learn how report cards, rulesets, and issue triage work in [Govern APIs using API Designer](./govern-apis.md).
+- Follow the complete workflow in [End-to-end tutorial](./end-to-end-tutorial.md).

docs/api-designer/govern-apis.md

@@ -0,0 +1,66 @@
+# Govern APIs using API Designer
+
+You can use API Designer to assess and improve your OpenAPI 3.x specification for AI readiness, design quality, and secure production use.
+
+![Governance Report](./images/analyze-view.png)
+
+## Why this matters
+
+- AI agents rely on clear descriptions, examples, and predictable API behavior.
+- Early governance helps you improve specification quality before publishing.
+
+## What you can review
+
+API Designer applies governance checks using Spectral rulesets and AI. You can review:
+
+- Overall scores and summary metrics.
+- Category-level breakdown to quickly identify weak areas.
+- Violations grouped by rule, severity, or area of the specification.
+
+## Reports in API Designer
+
+API Designer includes the following reports:
+
+| Report focus | What it emphasizes |
+|---------------|-------------------|
+| **WSO2 REST API AI Readiness Guidelines** | Readiness for AI agents and automated clients |
+| **WSO2 REST API Design Guidelines** | REST design quality and consistency |
+| **OWASP API Security Top 10** | API security best-practice checks |
+
+## AI readiness first
+
+AI readiness is a core governance area in API Designer. It helps you identify specification issues that block reliable agent usage.
+
+Focus on these first:
+
+- Missing or weak operation ids, summaries and descriptions.
+- Incomplete request and response examples.
+- Ambiguous parameter or schema intent.
+- Contract gaps that reduce machine readability.
+
+For each issue, review the provided details to understand what is wrong and why it affects agent behavior.
+
+### AI-assisted analysis (AI readiness)
+
+For **AI readiness**, API Designer combines **rule-based** results with **AI-assisted** narrative analysis: not only *what* failed a rule, but *why it matters* for agents and tools (for example ambiguous descriptions, weak examples, or gaps that cause wrong calls).
+
+You can run AI analysis on demand and get AI feedback to improve your specification.
+
+## How to fix findings
+
+You can resolve findings using:
+
+1. **GitHub Copilot Chat with the `api-design` skill**  
+   Use this for targeted fixes or rule-driven remediation.
+2. **Form-based editing in Design**  
+   Use this for precise changes to operations, parameters, responses, and schemas.
+
+## Important
+
+- Some fixes are **breaking** (for example path renames). Treat those as API **versioning** decisions, not silent edits.
+- Security items may require **real** URLs, policies, or auth server metadata—do not invent production values with AI.
+
+## Related topics
+
+- [Design APIs with API Designer](./design-apis.md) — create and refine your specification
+- [End-to-end tutorial](./end-to-end-tutorial.md) — full flow from draft to governance