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
docs: JR-339: Adds first draft of Getting Started with API Designer, … (#524)
* docs: JR-339: Adds first draft of Getting Started with API Designer, and adds associated attributes
* docs: JR-339: Adds prerequisite for running Service Registry instance
* JR-339: Minor tweaks
* docs: JR-339: Implements PR review comments
* docs: JR-339: Adds new section on creating schema design
As a developer of applications and services, you can use {product-long-api-designer} to ...
77
-
{product-long-api-designer} is a managed cloud service that enables you to design schema and API definitions without having to install, configure, run, and maintain your own {product-api-designer} clusters.
82
+
As a developer of applications and services, you can use {product-long-api-designer} to design event schemas and REST API definitions that comply with vendor-neutral and portable open specifications.
83
+
{product-long-api-designer} is a managed cloud service that enables you to design schemas and API definitions without having to install, configure, run, and maintain your own {product-api-designer} clusters.
78
84
79
-
For more overview information, see the https://access.redhat.com/documentation/en-us/red_hat_openshift_api-designer/1[{product-long-api-designer} user documentation^]
85
+
For more overview information, see the https://access.redhat.com/documentation/en-us/red_hat_openshift_api-designer/1[{product-long-api-designer} user documentation^].
80
86
81
87
ifndef::community[]
82
88
.Prerequisites
83
89
* You have a {org-name} account.
84
90
* You have a subscription to {product-long-kafka}.
91
+
* If you plan to store your designs in {product-long-registry}, you have a running {registry} instance (see {base-url}{getting-started-url-registry}[Getting started with {product-long-registry}^]).
85
92
//For more information about signing up, see *<@SME: Where to link?>*.
86
93
endif::[]
87
94
@@ -100,148 +107,189 @@ In this quick start, you'll learn how to ...
100
107
====
101
108
endif::[]
102
109
103
-
[id="proc-creating-schema-api-design_{context}"]
104
-
== Creating an {product-api-designer} schema or API design
110
+
[id="proc-creating-api-design_{context}"]
111
+
== Creating an API design
105
112
106
113
[role="_abstract"]
107
-
Use the {product-long-api-designer} web console to create an {product-api-designer} schema or API design.
114
+
Use the {product-long-api-designer} web console to create an OpenAPI or AsyncAPI definition.
108
115
109
116
ifndef::qs[]
110
117
.Prerequisites
111
118
* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
112
119
endif::[]
113
120
114
121
.Procedure
115
-
. In the {service-url-api-designer}[{product-api-designer} web console], click ...
116
-
. Click ...
122
+
. In the {service-url-api-designer}[{product-api-designer} web console], click *Create a schema or API design*.
123
+
. Complete the form to provide the details of the new design:
124
+
.. *Name*: Enter a unique design name, such as `my-api-design`.
125
+
.. *Summary*: Optional: Enter a short description of the design.
126
+
.. *Type*: Accept the default value *OpenAPI*, or select another API type from the list.
127
+
.. *Version*: OpenAPI only: Accept the default value *3.0.2*, or select another version from the list.
128
+
.. *Template*: Select the *Pet Store Example* template, or select another template from the list.
117
129
+
118
130
[.screencapture]
119
-
.Creating an {product-api-designer} design
120
-
image::create-api-designer-design.png[Image of page to create an {product-api-designer} design]
121
-
. Click ...
122
-
123
-
.Verification
124
-
ifdef::qs[]
125
-
* Is the new {product-api-designer} design listed in the designs table?
126
-
* Is ...
127
-
endif::[]
128
-
ifndef::qs[]
129
-
. Verify that the new {product-api-designer} design is listed in the designs table.
130
-
. Verify that ...
131
-
endif::[]
131
+
.Creating an API design
132
+
image::create-api-designer-design.png[Image of page to create an API design]
133
+
+
134
+
. Click *Create* to create the design. The design editor opens automatically.
135
+
. Select the design title and click the pen icon. Change the design title to *Orders* and click the *Save changes* icon.
136
+
. Click the *Design* tab, and optionally edit the design as follows:
137
+
.. Provide a version number and a description.
138
+
.. AsyncAPI only: Define terms of service.
139
+
.. Add your contact information (name, email address, and URL).
140
+
.. Select a license.
141
+
.. OpenAPI only: Define tags.
142
+
.. Define one or more servers.
143
+
.. Configure a security scheme.
144
+
.. OpenAPI only: Specify security requirements.
145
+
.. OpenAPI only: Configure vendor extensions.
146
+
+
147
+
[.screencapture]
148
+
.Editing an API design
149
+
image::api-designer-editor.png[Image of API design editor]
150
+
+
151
+
. Click the *Source* tab to see a live preview of the design.
152
+
The content of the *Source* tab automatically updates when you edit values on the editor page.
132
153
133
-
[id="proc-importing-schema-api-design_{context}"]
134
-
== Importing an {product-api-designer} schema or API design
154
+
. Optional: In the left pane of the design editor, you can add the following items:
155
+
.. OpenAPI: Resource paths, data types, and responses
156
+
.. AsyncAPI: Channels, data types, messages, operation traits, and message traits
157
+
. Click *Save* to save all changes and close the design editor.
135
158
136
-
[role="_abstract"]
137
-
You can import an {product-api-designer} schema or API design from a URL, from a file, or from an {product-long-registry} instance.
159
+
The new design is listed on the designs page. You can use the options icon (three vertical dots) to open the design editor, download the design to a file, or delete the design.
138
160
139
-
.Prerequisites
140
-
* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
141
-
142
-
.Procedure
143
-
. In the *{product-api-designer}* designs page of the web console, click ...
144
-
. Click ...
161
+
[.screencapture]
162
+
.{product-api-designer} design options menu
163
+
image::api-designer-design-options.png[Image of {product-api-designer} design options menu]
145
164
146
165
.Verification
147
166
ifdef::qs[]
148
-
* Is the imported {product-api-designer} design listed in the designs table?
149
-
* Is ...
167
+
* Is the new design listed on the {product-api-designer} designs page?
168
+
* Are the design details correct?
150
169
endif::[]
151
170
ifndef::qs[]
152
-
. Verify that the imported {product-api-designer} design is listed in the designs table.
153
-
. Verify that ...
171
+
. Verify that the new design is listed on the {product-api-designer} designs page.
172
+
. Verify that the design details are correct.
154
173
endif::[]
155
174
156
-
[id="proc-editing-schema-api-design_{context}"]
157
-
== Editing an {product-api-designer} schema or API design
175
+
[id="proc-creating-schema-design_{context}"]
176
+
== Creating a schema design
158
177
159
178
[role="_abstract"]
160
-
After you create or import an {product-api-designer} design, you can edit the schema or API content.
179
+
Use the {product-long-api-designer} web console to create an Apache Avro, JSON, or Google Protocol Buffers (Protobuf) event schema.
161
180
181
+
ifndef::qs[]
162
182
.Prerequisites
163
-
* You've created or imported an {product-api-designer} design.
183
+
* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
184
+
endif::[]
164
185
165
186
.Procedure
166
-
. In the *{product-api-designer}* designs page of the web console, select the {product-api-designer} design that you want to edit.
167
-
. Click ...
187
+
. In the {service-url-api-designer}[{product-api-designer} web console], click *Create a schema or API design*.
188
+
. Complete the form to provide the details of the new design:
189
+
.. *Name*: Enter a unique design name, such as `my-schema-design`.
190
+
.. *Summary*: Optional: Enter a short description of the design.
191
+
.. *Type*: From the list, select *Apache Avro*, or select another schema type.
192
+
+
193
+
[.screencapture]
194
+
.Creating a schema design
195
+
image::create-schema-design.png[Image of page to create a schema design]
196
+
+
197
+
. Click *Create* to create the design. The design editor opens automatically.
198
+
. Edit the design to provide your content.
199
+
+
200
+
[.screencapture]
201
+
.Editing a schema design
202
+
image::api-designer-schema-editor.png[Image of schema design editor]
203
+
+
204
+
. Click *Save* to save all changes and close the design editor.
205
+
206
+
The new design is listed on the designs page. You can use the options icon (three vertical dots) to open the design editor, download the design to a file, or delete the design.
168
207
169
208
.Verification
170
209
ifdef::qs[]
171
-
* Is ...?
210
+
* Is the new design listed on the {product-api-designer} designs page?
211
+
* Are the design details correct?
172
212
endif::[]
173
213
ifndef::qs[]
174
-
* Verify that ...
214
+
. Verify that the new design is listed on the {product-api-designer} designs page.
== Validating an {product-api-designer} schema or API design
218
+
[id="proc-importing-schema-api-design_{context}"]
219
+
== Importing an {product-long-api-designer} schema or API design
179
220
180
221
[role="_abstract"]
181
-
You can validate the schema or API content in an {product-api-designer} design.
222
+
You can import an event schema or API definition into {product-long-api-designer} from a URL, from a file, or from an {product-long-registry} instance.
182
223
183
224
.Prerequisites
184
-
* You've created, imported, or edited an {product-api-designer} design.
225
+
* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
226
+
* You can access a running {product-registry} instance, if you want to import from {registry}.
185
227
186
228
.Procedure
187
-
. In the *{product-api-designer}* designs page of the web console, select the {product-api-designer} design that you want to validate.
188
-
. Click ...
229
+
. In the {service-url-api-designer}[{product-api-designer} web console], click *Import a schema or API design*, and then click one of the following options:
230
+
.. *Import from file*: Click *Browse* and select a file, or drag and drop a file, and then click *Import*.
231
+
.. *Import from URL*: Enter a valid and accessible URL, and then click *Import*.
232
+
.. *Import from {registry}*: From the instances list, select a registry instance to show a list of its artifacts. Select an artifact, and then click *Import*.
233
+
. After you import the design, the design editor opens automatically.
234
+
. When you have finished editing, you can save your changes locally, download the content to a file, or export the updated design to {registry}.
189
235
190
236
.Verification
191
237
ifdef::qs[]
192
-
* Is ...?
238
+
* Is the imported design listed on the {product-api-designer} designs page?
239
+
* Are the design details correct?
193
240
endif::[]
194
241
ifndef::qs[]
195
-
* Verify that ...
242
+
. Verify that the imported design is listed on the {product-api-designer} designs page.
243
+
. Verify that the design details are correct.
196
244
endif::[]
197
245
198
246
[id="proc-exporting-schema-api-design_{context}"]
199
-
== Exporting {product-api-designer} designs
247
+
== Exporting an {product-long-api-designer} schema or API design
200
248
201
249
[role="_abstract"]
202
-
You can export an {product-api-designer} design to a file or to an {product-long-registry} instance.
250
+
After you create or import an {product-long-api-designer} event schema or API definition, you can export the content to an existing {product-long-registry} instance.
203
251
204
252
.Prerequisites
253
+
* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
205
254
* You've created or imported an {product-api-designer} design.
255
+
* You can access a running {product-registry} instance.
206
256
207
257
.Procedure
208
258
. In the *{product-api-designer}* designs page of the web console, select the {product-api-designer} design that you want to export.
209
-
. Click ...
210
-
211
-
.Verification
212
-
ifdef::qs[]
213
-
* Is ...?
214
-
endif::[]
215
-
ifndef::qs[]
216
-
* Verify that ...
217
-
endif::[]
218
-
219
-
[id="proc-deleting-schema-api-design_{context}"]
220
-
== Deleting {product-api-designer} designs
221
-
222
-
[role="_abstract"]
223
-
You can delete one or more {product-api-designer} designs in a single action.
224
-
225
-
.Prerequisites
226
-
* You've created or imported an {product-api-designer} design.
259
+
. Click *Edit* to open the design editor.
260
+
. From the *Save to* menu, click *Export to {registry}*.
261
+
. Complete the form to specify where the new design should be saved.
262
+
+
263
+
NOTE: If the design was originally imported from {product-registry}, the fields are prepopulated with the details of the original {product-registry} instance, and the *Version* is incremented.
264
+
+
265
+
.. *Registry instance*: Select the required instance from the list.
266
+
.. *Group*: Enter an optional unique group name such as `my-org` to organize the artifact in a named collection. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization.
267
+
+
268
+
NOTE: Specifying a group is optional when using the web console: {registry} generates a `default` group automatically.
269
+
+
270
+
.. *Artifact ID*: Enter an optional unique ID for this artifact, such as `my-ID`. If you don't specify a unique artifact ID, {registry} generates one automatically as a UUID.
271
+
.. *Version*: Specify the version number.
272
+
. Click *Save*.
227
273
228
-
.Procedure
229
-
. In the *{product-api-designer}* designs page of the web console, select the {product-api-designer} designs that you want to delete.
230
-
. Click ...
274
+
You can manage {product-long-api-designer} design versions in {product-long-registry}. You can also download {product-api-designer} designs to a file, either for local client code generation or to import the designs into {product-long-api-management}.
231
275
232
276
.Verification
233
277
ifdef::qs[]
234
-
* Is ...?
278
+
* Is the design listed as an artifact in {product-long-registry}?
279
+
* Are the artifact details correct?
235
280
endif::[]
236
281
ifndef::qs[]
237
-
* Verify that ...
282
+
* Verify that the design is listed as an artifact in {product-long-registry}.
283
+
* Verify that the artifact details are correct.
238
284
endif::[]
239
285
286
+
240
287
[role="_additional-resources"]
241
288
== Additional resources
242
289
* https://access.redhat.com/documentation/en-us/red_hat_openshift_api_designer/1[{product-long-api-designer} user documentation^]
290
+
* https://access.redhat.com/documentation/en-us/red_hat_openshift_api_management/1[{product-long-api-management} user documentation^]
243
291
* https://access.redhat.com/documentation/en-us/red_hat_openshift_service_registry/1[{product-long-registry} user documentation^]
244
-
* https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1[OpenShift Streams for Apache Kafka user documentation^]
292
+
* https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1[{product-long-kafka} user documentation^]
- Access to the <a href="https://console.redhat.com/application-services/api-designer">Red Hat OpenShift API Designer web console</a>
19
+
- A Red Hat user account to access the <a href="https://console.redhat.com/application-services/api-designer">Red Hat OpenShift API Designer web console</a>
20
+
- If you want to export to Service Registry, a running Service Registry instance (see the Getting started with Service Registry quick start)
0 commit comments