docs: JR-339: Additional updates to Getting Started (#533)

* chore: JR-339: Adds RHOAD to the PR check file

* docs: JR-339: Adds optional steps for testing the design and comparing versions; updates the import section; other minor tweaks

* docs: JR-339: Moves the 'testing' steps into a new section; moves and renames the 'show changes' step; adds links to Service Registry doc; minor formatting tweaks

* docs: JR-339: Implements review comments

* docs: JR-339: Updates based on latest UI changes

Author: bredamc

.github/workflows/modular-docs-check.yml

@@ -18,11 +18,12 @@ jobs:
             - product: RHOSR
             - product: RHOAS
             - product: RHOC
+            - product: RHOAD
 
     steps:
     - uses: actions/checkout@v2
       name: Checkout Source
-    - name: Use Node.js 
+    - name: Use Node.js
       uses: actions/setup-node@v2
       with:
         node-version: 16.6.2
@@ -38,7 +39,7 @@ jobs:
 
     - run: npm --prefix .build install
       name: Install Node Dependencies
-    
+
     - run: gem install asciidoctor tilt haml
       name: Install Asciidoctor
     - run: npm --prefix .build run generate:modular-docs

docs/api-designer/getting-started-api-designer/README.adoc

@@ -88,7 +88,6 @@ For more overview information, see the https://access.redhat.com/documentation/e
 ifndef::community[]
 .Prerequisites
 * You have a {org-name} account.
-* You have a subscription to {product-long-kafka}.
 * 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}^]).
 //For more information about signing up, see *<@SME: Where to link?>*.
 endif::[]
@@ -98,13 +97,13 @@ endif::[]
 ifdef::qs[]
 [#description]
 ====
-Learn how to create your first {product-api-designer} design in {product-long-api-designer}.
+Learn how to create your first API or schema design in {product-long-api-designer}.
 ====
 
 [#introduction]
 ====
 Welcome to the quick start for {product-long-api-designer}.
-In this quick start, you'll learn how to ...
+In this quick start, you'll learn how to create an API definition or event schema from a blank page or from a template, import an existing design to edit it, and export a finished design to {product-registry}.
 ====
 endif::[]
 
@@ -116,60 +115,47 @@ Use the {product-long-api-designer} web console to create an OpenAPI or AsyncAPI
 
 ifndef::qs[]
 .Prerequisites
-* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
+* You're logged in to the {product-long-api-designer} web console at {service-url-api-designer}[^].
 endif::[]
 
 .Procedure
-. In the {service-url-api-designer}[{product-api-designer} web console], click *Create a schema or API design*.
-. Complete the form to provide the details of the new design:
-.. *Name*: Enter a unique design name, such as `my-api-design`.
-.. *Summary*: Optional: Enter a short description of the design.
-.. *Type*: Accept the default value *OpenAPI*, or select another API type from the list.
-.. *Version*: OpenAPI only: Accept the default value *3.0.2*, or select another version from the list.
-.. *Template*: Select the *Pet Store Example* template, or select another template from the list.
-+
-[.screencapture]
-.Creating an API design
-image::create-api-designer-design.png[Image of page to create an API design]
-+
+. In the {service-url-api-designer}[{product-long-api-designer} web console^], click *Create design*.
+. Complete the form to provide the following details for the new design:
+* *Name*: Enter a unique design name, such as `my-api-design`.
+* *Description* _(Optional)_: Enter a short description of the design.
+* *Type*: Accept the default value *OpenAPI*, or select another API type from the list.
+* *Version* _(OpenAPI only)_: Accept the default value *3.0.2*, or select another version from the list.
+* *Template*: Select the *Pet Store Example* template, or select another template from the list.
 . Click *Create*. The new API design opens in the design editor.
 . Select the design title and click the pen icon. Change the design title to *Orders* and click the *Save changes* icon.
 . Click the *Design* tab, and optionally edit the design as follows:
-.. Provide a version number and a description.
-.. AsyncAPI only: Define terms of service.
-.. Add your contact information (name, email address, and URL).
-.. Select a license.
-.. OpenAPI only: Define tags.
-.. Define one or more servers.
-.. Configure a security scheme.
-.. OpenAPI only: Specify security requirements.
-.. OpenAPI only: Configure vendor extensions.
-+
-[.screencapture]
-.Editing an API design
-image::api-designer-editor.png[Image of API design editor]
-+
-. Click the *Source* tab to see a live preview of the design.
+* Provide a version number and a description.
+* _(AsyncAPI only)_ Define terms of service.
+* Add your contact information: name, email address, and URL.
+* Select a license.
+* _(OpenAPI only)_ Define tags.
+* Define one or more servers.
+* Configure a security scheme.
+* _(OpenAPI only)_ Specify security requirements.
+* _(OpenAPI only)_ Configure vendor extensions.
+. Click the *Source* tab, and review the live preview of the design.
 The content of the *Source* tab automatically updates when you edit values on the editor page.
-
-. Optional: In the left pane of the design editor, you can add the following items:
-.. OpenAPI: Resource paths, data types, and responses
-.. AsyncAPI: Channels, data types, messages, operation traits, and message traits
+. _(Optional)_ To see the changes that you made since the last save, click *Actions > Show changes*.
+. _(Optional)_ In the left pane of the design editor, you can add the following items:
+* _(OpenAPI only)_ Resource paths, data types, and responses
+* _(AsyncAPI only)_ Channels, data types, messages, operation traits, and message traits
 . Click *Save*.
 
-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.
-
-[.screencapture]
-.{product-api-designer} design options menu
-image::api-designer-design-options.png[Image of {product-api-designer} design options menu]
+The new design is listed on the *API and Schema Designs* page.
+You can use the options icon (three vertical dots) to view details about the design (including export and import events, and the edit history), rename the design, open the design editor, download the design to a file, export the design to {product-long-registry}, or delete the design.
 
 .Verification
 ifdef::qs[]
-* Is the new design listed on the {product-api-designer} designs page?
+* Is the new design listed on the designs page?
 * Are the design details correct?
 endif::[]
 ifndef::qs[]
-. Verify that the new design is listed on the {product-api-designer} designs page.
+. Verify that the new design is listed on the designs page.
 . Verify that the design details are correct.
 endif::[]
 
@@ -181,38 +167,31 @@ Use the {product-long-api-designer} web console to create an Apache Avro, JSON S
 
 ifndef::qs[]
 .Prerequisites
-* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
+* You're logged in to the {product-long-api-designer} web console at {service-url-api-designer}[^].
 endif::[]
 
 .Procedure
-. In the {service-url-api-designer}[{product-api-designer} web console], click *Create a schema or API design*.
-. Complete the form to provide the details of the new design:
-.. *Name*: Enter a unique design name, such as `my-schema-design`.
-.. *Summary*: Optional: Enter a short description of the design.
-.. *Type*: From the list, select *Apache Avro*, or select another schema type.
-+
-[.screencapture]
-.Creating a schema design
-image::create-schema-design.png[Image of page to create a schema design]
-+
+. In the {service-url-api-designer}[{product-long-api-designer} web console^], click *Create design*.
+. Complete the form to provide the following details for the new design:
+* *Name*: Enter a unique design name, such as `my-schema-design`.
+* *Description* _(Optional)_: Enter a short description of the design.
+* *Type*: From the list, select *Apache Avro*, or select another schema type.
 . Click *Create*. The new schema design opens in the design editor.
 . Edit the design source to provide your content.
-+
-[.screencapture]
-.Editing a schema design
-image::api-designer-schema-editor.png[Image of schema design editor]
-+
+. _(Optional)_ To see the changes that you made since the last save, click *Actions > Show changes*.
+. _(Optional)_ For Apache Avro or JSON Schema designs, you can click *Actions > Format content* to insert spaces and tabs that align your design content correctly.
 . Click *Save*.
 
-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.
+The new design is listed on the *API and Schema Designs* page.
+You can use the options icon (three vertical dots) to view details about the design (including export and import events, and the edit history), rename the design, open the design editor, download the design to a file, export the design to {product-long-registry}, or delete the design.
 
 .Verification
 ifdef::qs[]
-* Is the new design listed on the {product-api-designer} designs page?
+* Is the new design listed on the designs page?
 * Are the design details correct?
 endif::[]
 ifndef::qs[]
-. Verify that the new design is listed on the {product-api-designer} designs page.
+. Verify that the new design is listed on the designs page.
 . Verify that the design details are correct.
 endif::[]
 
@@ -223,62 +202,107 @@ endif::[]
 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.
 
 .Prerequisites
-* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
-* You can access a running {product-registry} instance in your organization, if you want to import from {registry}.
+* You're logged in to the {product-long-api-designer} web console at {service-url-api-designer}[^].
+* You can access a running {product-registry} instance in your organization, if you want to import from {product-long-registry}.
+For more information, see {base-url}{getting-started-url-registry}[Getting started with {product-long-registry}^].
 
 .Procedure
-. 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:
-.. *Import from file*: Click *Browse* and select a file, or drag and drop a file.
-.. *Import from URL*: Enter a valid and accessible URL.
-.. *Import from {registry}*: From the instances list, select a {registry} instance. Browse the list of artifacts for that instance, and select an artifact.
-. Click *Import*. The design editor opens automatically.
-
-When you finish editing, you can export the updated design to {registry} as a new artifact or as a new version of the existing artifact. You can also save your changes locally, or download the content to a file.
+. In the {service-url-api-designer}[{product-long-api-designer} web console^], click *Import design*, and then click one of the following options:
+* *Import from {registry}*: From the instances list, select a {registry} instance.
+Browse the list of artifacts for that instance, and select an artifact.
+* *Import from URL*: Enter a valid and accessible URL, and click *Fetch*.
+* *Import from file*: Click *Browse* and select a file, or drag and drop a file.
+. When prompted, provide additional information such as version (_OpenAPI only_), name, type, and description in the import dialog. You can overwrite any autopopulated values.
+. Click *Import*.
+The design editor opens automatically.
+
+When you finish editing, you can export the updated design to {registry} as a new artifact or as a new version of the existing artifact.
+You can export the design from the design editor or from the *API and Schema Designs* page.
+You can also save your changes locally, or download the content to a file.
 
 .Verification
 ifdef::qs[]
-* Is the imported design listed on the {product-api-designer} designs page?
+* Is the imported design listed on the designs page?
 * Are the design details correct?
 endif::[]
 ifndef::qs[]
-. Verify that the imported design is listed on the {product-api-designer} designs page.
+. Verify that the imported design is listed on the designs page.
 . Verify that the design details are correct.
 endif::[]
 
+[id="proc-testing-schema-api-design_{context}"]
+== Testing a schema or API design
+
+[role="_abstract"]
+You can test that your schema or API design content is valid and compatible with existing content by applying the rules of an existing {product-long-registry} instance.
+You can test the design while working in the {product-long-api-designer} editor, without exporting the design to {product-long-registry}.
+
+.Prerequisites
+* You're logged in to the {product-long-api-designer} web console at {service-url-api-designer}[^].
+* You've created or imported an {product-api-designer} design.
+* You can access a running {product-registry} instance in your organization.
+Within that instance, you know the artifact ID of an artifact with the required rules configured.
+For more information, see {base-url}{getting-started-url-registry}[Getting started with {product-long-registry}^].
+
+.Procedure
+. On the *API and Schema Designs* page of the {service-url-api-designer}[{product-long-api-designer} web console^], select the design that you want to test.
+. Click *Edit* to open the design editor.
+. From the *Actions* menu, click *Test using Service Registry*.
+. From the *Registry instance* list, select a {registry} instance.
+. In the *Group* and *ID* fields, specify the artifact details.
+. Click *Test*.
+
+A new pane in the design editor window shows the registration issues found by the test:
+
+* If the design content obeys the specified rules, the registration issues pane contains the following text:
+`Registry Test completed with no issues`
+
+* If the registration issues pane provides details of any issues, resolve the issues and click *Retry* to retest the content using the same rules.
+
+.Verification
+ifdef::qs[]
+* Is the registration issues pane shown in the design editor?
+* Are the test results correct?
+endif::[]
+ifndef::qs[]
+. Verify that the registration issues pane is shown in the design editor.
+. Verify that the test results are correct.
+endif::[]
+
 [id="proc-exporting-schema-api-design_{context}"]
 == Exporting a schema or API design
 
 [role="_abstract"]
 When you're happy with your changes to an {product-long-api-designer} event schema or API definition, and you want to use the design in your application, you can export the content to an existing {product-long-registry} instance.
 
 .Prerequisites
-* You're logged in to the {product-api-designer} web console at {service-url-api-designer}[^].
+* You're logged in to the {product-long-api-designer} web console at {service-url-api-designer}[^].
 * You've created or imported an {product-api-designer} design.
 * You can access a running {product-registry} instance in your organization.
+For more information, see {base-url}{getting-started-url-registry}[Getting started with {product-long-registry}^].
 
 .Procedure
-. In the *{product-api-designer}* designs page of the web console, select the {product-api-designer} design that you want to export.
-. Click *Edit* to open the design editor.
-. From the *Actions* menu, click *Export to {registry}*.
-. Complete the form to specify where the new design should be saved.
+. On the *API and Schema Designs* page of the {service-url-api-designer}[{product-long-api-designer} web console^], select the design that you want to export.
+. Click the options icon (three vertical dots), and click *Export to {registry}*.
+. Complete the form to specify where to save the new design. Provide the following details:
 +
-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.
+NOTE: If the design was originally imported from {product-long-registry}, the fields are prepopulated with the details of the original {product-registry} instance, and the *Version* is incremented.
 +
-.. *Registry instance*: Select the required instance from the list.
-.. *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.
+* *Registry Instance*: Select the required instance from the list.
+* *Group* _(Optional)_: Enter a 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.
 +
 NOTE:  Specifying a group is optional when using the web console: {registry} generates a `default` group automatically.
 +
-.. *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.
-.. *Version*: Specify the version number.
-+
-[.screencapture]
-.Exporting an API design
-image::export-api-designer-design.png[Image of page to export an API design]
-+
+* *ID* _(Optional)_: Enter a 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.
+* *Version* _(Optional)_: Specify the version number.
+If you don't specify a version number, {registry} sets the version to 1.
 . Click *Export*.
+The exported design is listed on the artifacts page of the specified {registry} instance.
 
-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}.
+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}.
 
 .Verification
 ifdef::qs[]
@@ -301,7 +325,7 @@ endif::[]
 ifdef::qs[]
 [#conclusion]
 ====
-Congratulations! You successfully completed the {product-api-designer} Getting Started quick start, and are now ready to use the service.
+Congratulations! You successfully completed the {product-long-api-designer} Getting Started quick start, and are now ready to use the service.
 ====
 endif::[]
 

docs/api-designer/getting-started-api-designer/quickstart.yml

@@ -23,6 +23,7 @@ spec:
     - !snippet/proc README.adoc#proc-creating-api-design
     - !snippet/proc README.adoc#proc-creating-schema-design
     - !snippet/proc README.adoc#proc-importing-schema-api-design
+    - !snippet/proc README.adoc#proc-testing-schema-api-design
     - !snippet/proc README.adoc#proc-exporting-schema-api-design
   conclusion: !snippet README.adoc#conclusion
   nextQuickStart: