# Spec-first Mode (Beta)
# Spec-first Mode (Beta)
**Spec-first Mode** is for teams that want API specification files to be the source of truth. In this mode, you design and maintain OpenAPI or Swagger files directly in Apidog, preview the generated API documentation as you edit, and keep the files synchronized with Git.
Use Spec-first Mode when your team already works with YAML or JSON specification files, reviews API changes through Git, or wants API design to fit naturally into a code repository workflow.
:::tip[Start from an existing specification]
To create a Spec-first project from an OpenAPI or Swagger file, see [Import OpenAPI Spec](https://docs.apidog.com/import-openapi-spec-635046m0.md). If you are migrating a Stoplight project with specifications, Markdown, models, images, or Git workflows, see [Import from Stoplight](https://docs.apidog.com/import-from-stoplight-2221427m0.md).
:::
## How Spec-first Mode Works
In a regular Apidog project, APIs are usually created and edited through visual forms. In a Spec-first project, the primary workspace is file-based.
You work with files such as:
- `openapi.yaml`
- `openapi.json`
- Swagger 2.0 files
- Markdown files and other supporting project files
Apidog parses the specification files and turns them into a navigable API structure. You can edit the raw files, use supported visual forms, validate the specification, preview generated documentation, and push changes back to Git.
## Create a Spec-first Project
Click **+ New Project**.
In the project type selector, choose **Spec-first Mode**.
Connect a Git provider, such as GitHub, GitLab, Azure DevOps, or Bitbucket.
Select an organization or workspace, then choose an existing repository or create a new repository if the option is available.
Select the main branch Apidog should synchronize with.
Choose whether to install a webhook.
Installing a webhook allows pushes in the Git repository to trigger automatic synchronization. This usually requires admin permission on the repository. If you do not have admin permission, you can skip webhook installation and sync manually.
Enter the project name, configure member permissions, and click **Create**.
After creation, Apidog performs the first synchronization. If the repository's default branch is not `main`, Apidog uses the repository branch name for the project main branch.
> Spec-first projects do not include sample project data. The API content comes from your specification files.
## The Specs Workspace
Spec-first projects include a **Specs** workspace in the left sidebar. This is the main place to manage specification files and Git sync.
The workspace contains three main areas:
- **File explorer**: Browse and manage files and folders from the synchronized repository.
- **API structure tree**: Navigate parsed OpenAPI content, such as overview, endpoints, schemas, and definitions.
- **Editor**: Edit files in code view or, for supported OpenAPI nodes, in form view.
When you select an endpoint, schema, or other supported node in the structure tree, Apidog opens the related part of the source file. This lets you move between the file-level view and the API-level view without leaving the Specs workspace.
## Edit Specification Files
The editor supports different file types and editing modes.
### Code View
Use **Code** view to edit YAML, JSON, Markdown, and other text files directly. This is the default way to work in Spec-first Mode.
### Form View
For supported OpenAPI nodes, Apidog also provides a **Form** view. This lets you edit common API fields through structured controls while keeping the underlying specification file as the source of truth.
Form view is available for supported nodes such as:
- API overview
- Endpoints
- Schemas
- Definitions
If the selected file or node cannot be edited in form view, Apidog keeps you in code view.
## Validate and Preview While Editing
Spec-first Mode includes validation and preview tools in the editor header.
### Validation
The **Validation** panel shows issues detected in the current specification, including warnings and errors. The validation badge displays the total number of detected issues.
Use this panel to find syntax problems, missing required fields, and rule violations before committing changes.
### Preview
The **Preview** panel shows how the selected specification node will appear in generated API documentation.
Preview is available for:
- API overview
- Endpoints
- Schemas
- Definitions
For endpoints, Preview includes:
- **Docs**: The generated endpoint documentation.
- **Try it out**: A request panel for sending a request based on the selected endpoint definition.
For schemas, definitions, and overview nodes, Preview shows the generated documentation view.
Validation and Preview use the same side panel. Opening one closes the other.
## Sync Changes from Git
When other team members push changes to the connected repository, you can pull the latest files into Apidog.
Open the **Specs** workspace.
Click the current branch name in the Specs sidebar.
Click **Git Pull**.
If webhook sync is installed, Apidog can also receive push events from the Git provider and trigger synchronization automatically.
## Commit and Push Changes to Git
After editing files in Apidog, push your changes back to the connected repository.
Edit one or more files in the Specs workspace.
Click **Changes** to review modified, added, renamed, and deleted files.
Click **Commit & Push**.
In the **Push to Git repo** modal, select the files you want to include.
Enter a commit message.
Click **Push**.
If you do not want to keep your local edits, use **Discard all changes** before pushing.
## Manage Branches
Spec-first Mode supports branch-based collaboration. Apidog maps synchronized Git branches to project branches so you can switch between versions of the specification.
### Switch Branches
Click the branch name in the Specs sidebar and select another branch from the dropdown.
### Track an Existing Git Branch
If a branch exists in Git but has not been imported into Apidog, click **Import New Branch**, select the branch, and import it. Apidog then starts tracking and synchronizing that branch.
### Create a Branch
Open **Project Settings > Git & Branches** and click **New Branch** to create a branch from an existing project branch.
### Re-sync a Branch
If a branch sync fails or the files look out of date, use **Re-sync** in **Project Settings > Git & Branches**. This resets the sync state for that branch and imports the files again.
### View Sync Logs
If a sync fails, open the branch actions and choose **View Logs** to inspect the sync details.
### Stop Tracking or Delete a Branch
Deleting a tracked branch removes it from Apidog's sync configuration. For non-main branches, the project branch record can also be removed.
## Webhook Sync and Permissions
Webhook sync is optional but recommended for teams that want Apidog to stay up to date with repository pushes.
When webhook sync is enabled:
- Apidog registers a webhook on the connected Git provider.
- Only supported push events are processed.
- Apidog verifies the webhook signature or token before syncing.
Permission requirements:
- Installing a webhook usually requires repository admin permission.
- Pushing changes requires write permission.
- If webhook installation is skipped, manual sync is still available.
If you skipped webhook installation during project creation, you can install it later from **Project Settings > Git & Branches**.
## Storage-backed Spec-first Projects
Some Spec-first projects may use Apidog's internal storage instead of an external Git repository.
These projects still use the Specs workspace, file-based editing, validation, preview, and branch management.
The UI labels are slightly different:
- **Git Pull** appears as **Sync**.
- **Commit & Push** appears as **Save**.
- Git provider information and external webhook settings are hidden.
## Notes and Limitations
- Spec-first Mode is currently in beta.
- The Specs workspace appears only in Spec-first projects.
- Spec-first projects do not create sample API data.
- The specification file is the **source of truth**. Changes should be made through the Specs workspace or synchronized through Git.
- Webhook installation may fail **if you do not have enough repository permission**. You can still use manual sync if you have write access.