Merge pull request #2956 from pwright/min-docs-api-controller

minimal api-controller-docs

docs/modules/ROOT/partials/con-studio-overview.adoc

@@ -3,42 +3,64 @@
 
 {studio-long} enables you to design schemas and API definitions. It provides a web console to make it easy for API owners and developers to manage the content of event schemas and API definitions.
 
-You can use {studio} to create a schema or API design from a simple template, use one of the detailed templates provided, or import an existing design to edit it. When you’re happy with your content, you can save your design to a file, and export it to {registry-long} or use it in your client applications.
+ifndef::apicurio-studio-downstream[]
+You can use {studio} to create a schema or API design from a simple template, use one of the detailed templates provided, or import an existing design to edit it.
+endif::[]
 
 ifdef::apicurio-studio-downstream[]
+You can use {studio} to create a schema or API design from a simple template, use one of the detailed templates provided, or import an existing design to edit it. 
+As you evolve your design, it is saved automatically to {registry-long} as `DRAFT`.
+When you are happy with your content, you can promote your design to `ENABLED` in {registry}.
+
 {studio-long} is based on the https://github.com/Apicurio/apicurio-studio[Apicurio Studio] open source community project.
 endif::[]
 
-[id="studio-key-concepts"]
-== Key concepts
+.Key concepts
 
-To understand how {studio-long} works, it’s important to understand the following key concepts:
+To understand how {studio-long} works, it is important to understand the following key concepts:
 
-* *{studio-long} web console*
+{studio} web console:: The web environment where developers create, manage, and organize their API and schema designs.
 +
-The web environment where users from an organization can manage designs.
+--
+You can use the {studio-long} web console to complete the following tasks:
 
-* *Design*
+* Browse and search the schema and API designs that are stored in {studio-long}
+* Add new schema and API designs and versions
+* Import content from a file, from a URL, or from a {registry-long} instance
+* Show the changes that you have made in your current editing session
+--
+
+Design:: An API design or schema design. When downloaded to a local project, or used in {registry}, designs are referred to as _artifacts_.
 +
-An API design or schema design. When downloaded to a local project, or exported into {registry-long}, designs are referred to as _artifacts_.
+--
+{studio-long} supports the following API types:
+
+* AsyncAPI
+* OpenAPI
 
-[id="studio-capabilities"]
-== {studio-long} capabilities
+{studio-long} supports the following schema types:
 
-The {studio-long} has the following key capabilities:
+* Apache Avro
+* JSON Schema
+* Google Protocol Buffers (Protobuf)
+--
 
-* Creation of APIs and schemas in a visual editor
-* Increased developer productivity with code and test generation from downloaded designs
 
-[id="studio-use-cases"]
-== {studio-long} use cases
+.{studio} use cases
 
 The main use cases for {studio} are as follows:
 
 * *Contract-first application development*
 +
-You can use {studio-long} to visually design the API and data models (_contracts_) required by your applications, before you write any application code. After you define the contract, it’s much easier to create the application logic needed to satisfy the contract. You can generate Quarkus-based client and server applications from designs created in {studio-long}.
+You can use {studio} to visually design the API and data models (_contracts_) required by your applications, before you write any application code. 
+After you define the contract, it is easier to create the application logic needed to satisfy the contract. You can generate Quarkus-based client and server applications from designs created in {studio}.
 
-* *Schema editing for Kafka applications*
+ifdef::apicurio-studio-downstream[]
+
+* *Population of {registry}*
 +
-When you use Kafka to produce and consume messages, you can define the data shape of your message payloads by using one of a number of event schema types. When you need to define a new schema, you can use {studio-long}.
+All API and schema designs are saved to {registry}.
+You can use {registy} features, for example:
+* Creating rules for design change validation.
+* Using the {registry} REST API to dereference complex JSON Schemas.
+endif::[]

docs/modules/ROOT/partials/proc-creating-api-draft.adoc

@@ -0,0 +1,62 @@
+[id="proc-creating-api-draft"]
+= Creating an API draft
+
+[role="_abstract"]
+Use the {studio-long} web console to create an OpenAPI or AsyncAPI definition.
+
+.Prerequisites
+* You're logged in to the {studio} web console.
+
+.Procedure
+. In the {studio} web console, click *Create draft*.
+. Complete the wizard to provide the following details for the new draft:
+
+.. Specify the *Draft Coordinates* and click *Next*:
++
+*  *Group ID & Draft ID*: Use the default empty settings to automatically generate an Draft ID and add the Draft to the `default` Draft group. Alternatively, you can enter an optional Group ID or Draft ID.
+* *Version number*: Optionally specify a version number.
+* *Type*: Use the default *Auto-Detect* setting to automatically detect the Draft type (not allowed if creating an empty Draft), or select the Draft type from the list, for example, *OpenAPI*. 
+
+
+.. Specify the *Draft Content* and click *Next*:
++
+** *From template*: Choose from the list of templates.
+* *From local file*: Click *Browse*, and select a file, or drag and drop a file. For example, `my-openapi.json` or `my-schema.proto`. Alternatively, you can enter the file contents in the text box.
+* *From URL*: Enter a valid and accessible URL, and click *Fetch*. For example: `\https://petstore3.swagger.io/api/v3/openapi.json`.
+
+
+.. Specify the *Draft Metadata*:
++
+** *Name*: Enter an optional friendly name for the first artifact version.
+** *Description*: Enter an optional description for the first artifact version.
+
+. Click *Create* to create the draft.
+The Draft details view is displayed.
+
+. To edit the draft, click *Edit draft*.
++
+.. Click the *Design* tab, and optionally edit the draft 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.
+.. Click the *Source* tab, and review the live preview of the draft.
+The content of the *Source* tab automatically updates when you edit values on the editor page.
+.. _(Optional)_ To see the changes that you made since the last save, click *Actions > Show draft changes*.
+.. _(Optional)_ In the left pane of the draft 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*.
+.. Use the breadcrumbs to navigate back to the *Drafts* page.
+
+The new draft is listed on the *Drafts* page using the Group ID and Draft ID.
+You can use the options icon (three vertical dots) to view the draft details, edit the draft content, finalize the draft, view the draft in {registry}, or delete the draft.
+
+.Additional information
+
+See xref:proc-finalizing-draft[]

docs/modules/ROOT/partials/proc-creating-schema-draft.adoc

@@ -0,0 +1,50 @@
+[id="proc-creating-schema-draft"]
+= Creating a schema draft
+
+[role="_abstract"]
+Use the {studio-long} web console to create an Apache Avro, JSON Schema, or Google Protocol Buffers (Protobuf) event schema.
+
+.Prerequisites
+* You're logged in to the {studio} web console.
+
+.Procedure
+. In the {studio} web console, click *Create draft*.
+. Complete the wizard to provide the following details for the new draft:
+
+.. Specify the *Draft Coordinates* and click *Next*:
++
+*  *Group ID & Draft ID*: Use the default empty settings to automatically generate an Draft ID and add the Draft to the `default` Draft group. Alternatively, you can enter an optional Group ID or Draft ID.
+* *Version number*: Optionally specify a version number.
+* *Type*: Use the default *Auto-Detect* setting to automatically detect the Draft type (not allowed if creating an empty Draft), or select the Draft type from the list, for example, *Apache Avro*. 
+
+
+.. Specify the *Draft Content* and click *Next*:
++
+** *From template*: Choose from the list of templates.
+* *From local file*: Click *Browse*, and select a file, or drag and drop a file. For example, `my-openapi.json` or `my-schema.proto`. Alternatively, you can enter the file contents in the text box.
+* *From URL*: Enter a valid and accessible URL, and click *Fetch*. For example: `\https://petstore3.swagger.io/api/v3/openapi.json`.
+
+
+.. Specify the *Draft Metadata*:
++
+** *Name*: Enter an optional friendly name for the first artifact version.
+** *Description*: Enter an optional description for the first artifact version.
+
+. Click *Create* to create the draft.
+The Draft details view is displayed.
+
+. To edit the draft, click *Edit draft*.
++
+.. Click the *Design* tab, and edit the draft.
+.. _(Optional)_ To see the changes that you made since the last save, click *Actions > Show draft changes*.
+.. _(Optional)_ In the left pane of the draft editor, you can add the following items:
+.. Click *Save*.
+.. Use the breadcrumbs to navigate back to the *Drafts* page.
+
+The new draft is listed on the *Drafts* page using the Group ID and Draft ID.
+You can use the options icon (three vertical dots) to view the draft details, edit the draft content, finalize the draft, view the draft in {registry}, or delete the draft.
+
+
+.Additional information
+
+See xref:proc-finalizing-draft[]