You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
First sign up for a free Speakeasy account at [https://app.speakeasy.com](https://app.speakeasy.com).
32
-
33
-
New accounts start with a 14 day free trial of Speakeasy's business tier, to enable users to try out every SDK generation feature. At the end of the trial, accounts will revert to the free tier. No credit card is required.
34
-
35
-
Free accounts can continue to generate one SDK with up to 50 API methods free of charge.
36
-
37
-
---
38
-
39
29
## Install the Speakeasy CLI
40
30
41
31
After signing up, install the Speakeasy CLI using one of the following methods:
@@ -77,11 +67,17 @@ For first-time SDK generation, run `speakeasy quickstart`.
77
67
speakeasy quickstart
78
68
```
79
69
70
+
### Authentication & account creation
71
+
80
72
The CLI will prompt for authentication with a Speakeasy account. A browser window will open to select a workspace to associate with the CLI. Workspaces can be changed later if required.
81
73
82
-
---
74
+
If you've not previously signed up for an account, you will be prompted to create one.
83
75
84
-
## Upload an OpenAPI document
76
+
New accounts start with a 14 day free trial of Speakeasy's business tier, to enable users to try out every SDK generation feature. At the end of the trial, accounts will revert to the free tier. No credit card is required.
77
+
78
+
Free accounts can continue to generate one SDK with up to 50 API methods free of charge. Please refer to the pricing page for update information on each [pricing tier](https://www.speakeasy.com/pricing).
79
+
80
+
### Upload an OpenAPI document
85
81
86
82
After authentication, the system prompts for an OpenAPI document:
87
83
@@ -115,14 +111,10 @@ Provide either a link to a remote hosted OpenAPI document, or a relative path to
115
111
116
112
</Callout>
117
113
118
-
---
119
-
120
-
## Select an SDK language
121
-
122
-
After configuring the OpenAPI document, the next step prompt is to name the SDK. It's best to name the SDK after the company or project it serves.
123
-
124
-
Choose target language:
114
+
### Select artifact type
125
115
116
+
After configuring the OpenAPI document, the next step prompt is to choose the type of artifact being generated: SDK or MCP. Select SDK, and a prompt will appear to choose the target language:
117
+
Choosing Terraform will default you back to the CLI native onboarding. [Editor support for Terraform previews](https://roadmap.speakeasy.com/roadmap?id=a8164ebf-55e1-4376-b42e-4e040c085586) coming soon.
126
118
<Screenshot
127
119
variant="cli"
128
120
image={{
@@ -131,11 +123,11 @@ Choose target language:
131
123
}}
132
124
/>
133
125
134
-
For each language,Speakeasy has crafted generators with language experts to be highly idiomatic. Follow the links below for all the details on the design decisions that have gone into each language we support:
126
+
For each language,Speakeasy has crafted generators with language experts to be highly idiomatic. Follow the links below for all the details on the design decisions that have gone into each language we support:
135
127
136
128
<CardGridcards={supportedLanguages} />
137
129
138
-
## Complete the SDK configuration
130
+
###Complete the SDK configuration
139
131
140
132
Speakeasy validates the specifications and generates the SDK after receiving all inputs. The process executes [`speakeasy run`](/docs/speakeasy-reference/cli/run) to validate, generate, compile, and set up the SDK. A confirmation message displays the generated SDK details upon successful completion:
141
133
@@ -147,9 +139,7 @@ Speakeasy validates the specifications and generates the SDK after receiving all
147
139
}}
148
140
/>
149
141
150
-
---
151
-
152
-
## Iterating on the SDK
142
+
## Iterating on the SDK with Studio
153
143
154
144
If the SDK is successfully generated, there will be a prompt asking the user to open the SDK studio. The Studio is a web GUI that helps users make look & feel improvements to their SDKs. It uses [OpenAPI Overlays](/openapi/overlays) to preserve the original OpenAPI specification while allowing users to make changes to the generated SDK.
title: "Iterate on your OpenAPI document with the OpenAPI Editor"
3
+
description: "Use Speakeasy's OpenAPI Editor to create, edit, and manage your OpenAPI documents. Prepare OpenAPI specs for SDK generation."
4
+
asIndexPage: true
5
+
---
6
+
7
+
# Iterate on your OpenAPI document with the OpenAPI Editor
8
+
9
+
The Speakeasy OpenAPI Editor provides a web-based interface for editing and managing OpenAPI specifications. The editor includes real-time validation, AI-powered suggestions, and a non-destructive overlay system that preserves source integrity while enabling customization.
10
+
11
+
## Edit with the overlay system
12
+
13
+
The overlay system captures all changes as separate transformations that reapply automatically when the source specification regenerates. This approach prevents customizations from being overwritten.
14
+
15
+
16
+
17
+
### How overlays work
18
+
19
+
When editing a field:
20
+
21
+
1. Changes save as an overlay, not as direct modifications to the source
22
+
2. The overlay system tracks the specific path and transformation
23
+
3. On source regeneration, overlays reapply automatically
24
+
4. Conflicts surface in the editor for manual resolution
25
+
26
+
This system is particularly useful for teams using code-first API development, where specifications generate from source code but require additional documentation or examples.
27
+
28
+
For more information on OpenAPI Overlays, see [here](/docs/prep-openapi/overlays/create-overlays).
29
+
30
+
## Lint and validate specifications
31
+
32
+
The editor provides real-time linting and validation to catch errors and improve specification quality.
33
+
34
+
35
+
36
+
### Built-in validation
37
+
38
+
Automatic validation catches common issues:
39
+
40
+
-**Syntax errors**: Invalid YAML or JSON structure
41
+
-**Schema violations**: Fields that don't conform to OpenAPI specification
42
+
-**Reference errors**: Broken `$ref` pointers to components
43
+
-**Semantic issues**: Logical inconsistencies like duplicate operation IDs
44
+
45
+
Errors and warnings appear inline in the editor and in the validation panel. Select any issue to jump directly to the problematic line.
46
+
47
+
For a full list of linting rules please see, [here](/docs/prep-openapi/linting).
48
+
49
+
## Preview Artifact changes
50
+
51
+
The preview pane displays how specification changes affect generated SDKs and documentation in real-time.
52
+
53
+
54
+
55
+
### Available preview modes
56
+
57
+
Toggle between preview modes to explore the different types of artifacts you can generate:
58
+
59
+
-**SDKs**: Generated client libraries in supported languages
60
+
-**MCP servers**: Method signatures, parameters, and return types
61
+
-**Terraform (Coming Soon!)**: Resource definitions and usage examples
62
+
63
+
Changes made to the spec in the editor update the preview instantly, providing immediate feedback on how modifications affect the developer experience.
64
+
65
+
### Multi-language preview
66
+
67
+
Select target languages to preview SDK generation across different programming environments:
68
+
69
+
70
+
71
+
The preview uses the same generation logic as production SDK builds, ensuring accuracy.
72
+
73
+
## Next steps
74
+
75
+
The OpenAPI Editor streamlines specification management through its overlay system, real-time validation, and instant SDK preview capabilities. Import specifications from any source, edit safely with non-destructive overlays, and validate changes before SDK generation. The editor integrates seamlessly into existing CLI workflows, requiring no changes to build pipelines or development processes.
0 commit comments