clean up registry user docs and restructure (#1004)

Apicurio · Nov 11, 2020 · baf90b6 · baf90b6
1 parent e4d1588
commit baf90b6
Show file tree

Hide file tree

Showing 37 changed files with 360 additions and 369 deletions.
diff --git a/docs/local-test-playbook.yml b/docs/local-test-playbook.yml
@@ -27,9 +27,9 @@ asciidoc:
     mod-loc: partial$
     registry-overview: link:assembly-intro-to-the-registry.html[Introduction to Apicurio Registry]
     registry-rules: link:assembly-intro-to-registry-rules.html[Introduction to Apicurio Registry rules]
-    registry-artifact-types: link:assembly-registry-reference.html[Apicurio Registry reference] 
-    registry-rule-types: link:assembly-registry-reference.html[Apicurio Registry reference]
-    registry-rule-maturity-matrix: link:assembly-registry-reference.html[Apicurio Registry reference]
+    registry-reference: link:assembly-registry-reference.html[Apicurio Registry artifact reference] 
     managing-registry-artifacts-ui: link:assembly-managing-registry-artifacts-ui.html[Managing Apicurio Registry content using the web console]
+    managing-registry-artifacts-api: link:assembly-managing-registry-artifacts-api.html[Managing Apicurio Registry content using the REST API]
     installing-the-registry-docker: link:assembly-installing-the-registry-docker.html[Installing Apicurio Registry using Docker]
     installing-the-registry-openshift: link:assembly-installing-the-registry-openshift.html[Installing Apicurio Registry on OpenShift]
+    kafka-client-serdes: link:assembly-using-kafka-client-serdes.html[Validating schemas using Kafka client serializers/deserializers]
diff --git a/docs/modules/ROOT/assets/attachments/registry-rest-api.htm b/docs/modules/ROOT/assets/attachments/registry-rest-api.htm
@@ -16,7 +16,7 @@
     </style>
   </head>
   <body>
-    <redoc spec-url='https://raw.githubusercontent.com/Apicurio/apicurio-registry/master/common/src/main/resources/META-INF/openapi.json'></redoc>
+    <redoc spec-url='https://raw.githubusercontent.com/Apicurio/apicurio-registry/1.3.x/common/src/main/resources/META-INF/openapi.json'></redoc>
     <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
   </body>
 </html>
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,13 +1,14 @@
 * xref:getting-started/assembly-intro-to-the-registry.adoc[]
 * xref:getting-started/assembly-intro-to-registry-rules.adoc[]
 ifdef:getting-started/:apicurio-registry[]
-* xref:getting-started/assembly-installing-the-registry-docker.adoc[]
+* xref:getting-started/assembly-installing-registry-docker.adoc[]
 endif:getting-started/:[]
-* xref:getting-started/assembly-installing-the-registry-openshift.adoc[]
+* xref:getting-started/assembly-installing-registry-openshift.adoc[]
+* xref:getting-started/assembly-installing-registry-storage-openshift.adoc[]
 * xref:getting-started/assembly-configuring-the-registry.adoc[]
 * xref:getting-started/assembly-managing-registry-artifacts-ui.adoc[]
 * xref:getting-started/assembly-managing-registry-artifacts-api.adoc[]
 * xref:getting-started/assembly-managing-registry-artifacts-maven.adoc[]
-* xref:getting-started/assembly-using-kafka-client-serdes.adoc[]
 * xref:getting-started/assembly-using-the-registry-client.adoc[]
+* xref:getting-started/assembly-using-kafka-client-serdes.adoc[]
 * xref:getting-started/assembly-registry-reference.adoc[]
diff --git a/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc b/docs/modules/ROOT/pages/getting-started/assembly-configuring-the-registry.adoc
@@ -2,7 +2,7 @@
 include::{mod-loc}shared/all-attributes.adoc[]
 
 [id="configuring-the-registry"]
-= Configuring {registry} on OpenShift
+= Managing {registry} deployment on OpenShift
 
 This chapter explains how to configure optional settings for {registry} health checks on OpenShift:
 

diff --git a/...embly-installing-the-registry-docker.adoc → .../assembly-installing-registry-docker.adoc b/...embly-installing-the-registry-docker.adoc → .../assembly-installing-registry-docker.adoc
diff --git a/.../modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc b/.../modules/ROOT/pages/getting-started/assembly-installing-registry-openshift.adoc
@@ -0,0 +1,25 @@
+// Metadata created by nebel
+
+include::{mod-loc}shared/all-attributes.adoc[]
+
+[id="installing-registry-ocp"]
+= Installing {registry} on OpenShift
+
+This chapter explains how to install {registry}:
+
+* xref:installing-registry-operatorhub[]
+//* xref:installing-registry-kafka-streams-template-storage[]
+
+.Prerequisites
+* {registry-overview}
+
+NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on the number and type of artifacts stored in {registry}, and on your chosen storage option, for example, Kafka Streams, database, Infinispan cluster configuration.
+
+ifdef::apicurio-registry[]
+.Additional resources
+* For details on building from source, see https://github.com/Apicurio/apicurio-registry.
+endif::[]
+
+//INCLUDES
+//include::{mod-loc}getting-started/proc_installing-registry-kafka-streams-template-storage.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/proc-installing-registry-operatorhub.adoc[leveloffset=+1]
diff --git a/...ly-installing-the-registry-openshift.adoc → ...nstalling-registry-storage-openshift.adoc b/...ly-installing-the-registry-openshift.adoc → ...nstalling-registry-storage-openshift.adoc
@@ -1,19 +1,10 @@
 // Metadata created by nebel
-
 include::{mod-loc}shared/all-attributes.adoc[]
 
-[id="installing-the-registry"]
-= Installing {registry} on OpenShift
-
-This chapter explains how to first install {registry} and then how to set up your chosen registry storage option: {kafka-streams}, embedded Infinispan, or PostgreSQL database.
-
-.Prerequisites
-* {registry-overview}
+[id="installing-registry-storage"]
+= Installing {registry} storage on OpenShift
 
-.{registry} installation
-* xref:installing-registry-operatorhub[]
-//* xref:installing-registry-kafka-streams-template-storage[]
-* xref:configuring-registry-ui[]
+This chapter explains how to install and configure your chosen registry storage option: {kafka-streams}, embedded Infinispan, or PostgreSQL database.
 
 .{kafka-streams} storage
 * xref:installing-kafka-streams-operatorhub[]
@@ -44,17 +35,11 @@ These features provide early access to upcoming product features, enabling custo
 ====
 endif::[]
 
-NOTE: You can install more than one instance of {registry} depending on your environment. The number of instances depends on your storage option, for example, your Kafka, Infinispan, or database cluster configuration, and on the number and type of artifacts stored in {registry}.
-
-ifdef::apicurio-registry[]
-.Additional resources
-* For details on building from source, see https://github.com/Apicurio/apicurio-registry.
-endif::[]
+.Prerequisites
+* {installing-the-registry-openshift}
 
 //INCLUDES
 //include::{mod-loc}getting-started/proc_installing-registry-kafka-streams-template-storage.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-installing-registry-operatorhub.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-installing-kafka-streams-operatorhub.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-setting-up-kafka-streams-storage.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-setting-up-infinispan-storage.adoc[leveloffset=+1]

diff --git a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-registry-rules.adoc
@@ -12,6 +12,5 @@ This chapter introduces the optional rules used to govern registry content and p
 * xref:registry-rules-apply[]
 * xref:registry-rules-work[]  
 
-
 //INCLUDES
 include::{mod-loc}getting-started/con-registry-rules.adoc[leveloffset=+1]
diff --git a/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc b/docs/modules/ROOT/pages/getting-started/assembly-intro-to-the-registry.adoc
@@ -11,7 +11,6 @@ This chapter introduces {registry} concepts and features and provides details on
 * xref:registry-overview[]
 * xref:registry-artifacts[]
 * xref:registry-web-console[]
-* xref:registry-rest-api[]
 * xref:registry-storage[]
 * xref:client-serde[]
 * xref:kafka-connect[]
@@ -22,7 +21,6 @@ This chapter introduces {registry} concepts and features and provides details on
 include::{mod-loc}getting-started/con-registry-overview.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/con-registry-artifacts.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/con-registry-web-console.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/con-registry-rest-api.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/con-registry-storage.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/con-registry-serde.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/con-kafka-connect-converters.adoc[leveloffset=+1]

diff --git a/...odules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc b/...odules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-api.adoc
@@ -6,11 +6,14 @@ include::{mod-loc}shared/all-attributes.adoc[]
 = Managing {registry} content using the REST API
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
-This chapter explains how to manage artifacts stored in the registry using the Registry REST API. This includes using Registry REST API commands, a Maven plug-in, or a Java client application:
+This chapter describes the Registry REST API and shows how to use it manage artifacts stored in the registry:
 
+* xref:registry-rest-api[] 
 * xref:managing-artifacts-using-rest-api[]
-* xref:managing-artifacts-using-client-code[]
+
+.Additional resources
+* link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
 
 //INCLUDES
+include::{mod-loc}getting-started/con-registry-rest-api.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-managing-artifacts-using-rest-api.adoc[leveloffset=+1]
-include::{mod-loc}getting-started/proc-managing-artifacts-using-client-code.adoc[leveloffset=+1]
diff --git a/...ules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc b/...ules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-maven.adoc
@@ -5,9 +5,14 @@ include::{mod-loc}shared/all-attributes.adoc[]
 [id="managing-registry-artifacts-maven"]
 = Managing {registry} content using the Maven plug-in
 
-This chapter explains how to manage artifacts stored in the registry using the {registry} Maven plug-in.
+This chapter explains how to manage artifacts stored in the registry using the {registry} Maven plug-in:
 
 * xref:managing-artifacts-using-maven-plugin[]
 
+.Prerequisites
+* See {registry-overview}
+* {registry} must be installed and running in your environment
+* Maven must be installed and configured in your environment
+
 //INCLUDES
 include::{mod-loc}getting-started/proc-managing-artifacts-using-maven-plugin.adoc[leveloffset=+1]
diff --git a/...modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc b/...modules/ROOT/pages/getting-started/assembly-managing-registry-artifacts-ui.adoc
@@ -8,11 +8,13 @@ include::{mod-loc}shared/all-attributes.adoc[]
 
 This chapter explains how to manage artifacts stored in the registry using the {registry} web console. This includes uploading and browsing registry content, and configuring optional rules:
 
+* xref:configuring-registry-ui[]
 * xref:adding-artifacts-using-console[]
 * xref:browsing-artifacts-using-console[]
 * xref:configuring-rules-using-console[]
 
 //INCLUDES
+include::{mod-loc}getting-started/proc-configuring-registry-ui.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-adding-artifacts-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-browsing-artifacts-using-console.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/proc-configuring-rules-using-console.adoc[leveloffset=+1]
diff --git a/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc b/docs/modules/ROOT/pages/getting-started/assembly-registry-reference.adoc
@@ -3,20 +3,24 @@
 include::{mod-loc}shared/all-attributes.adoc[]
 
 [id="artifact-and-rule-types"]
-= {registry} reference
+= {registry} artifact reference
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
-This chapter lists the supported artifact types, states and content rule types that are stored in {registry}.
+This chapter provides details on the supported artifact types, states, metadata, and content rules that are stored in {registry}.
+
 * xref:registry-artifact-types[]
 * xref:registry-artifact-states[]
+* xref:registry-artifact-metadata[]
 * xref:registry-rule-types[]
 * xref:registry-rule-maturity-matrix[]
 
+
 .Additional resources
-* For more detailed information on artifact types, states, and rule types, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
+* For more detailed information, see the link:{attachmentsdir}/registry-rest-api.htm[Apicurio Registry REST API documentation]
 
 //INCLUDES
 include::{mod-loc}getting-started/ref-registry-artifact-types.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-artifact-states.adoc[leveloffset=+1]
+include::{mod-loc}getting-started/ref-registry-artifact-metadata.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-rule-types.adoc[leveloffset=+1]
 include::{mod-loc}getting-started/ref-registry-rule-maturity-matrix.adoc[leveloffset=+1]
diff --git a/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc b/docs/modules/ROOT/pages/getting-started/assembly-using-kafka-client-serdes.adoc
@@ -3,12 +3,12 @@
 include::{mod-loc}shared/all-attributes.adoc[]
 
 [id="using-kafka-client-serdes"]
-= Using the Kafka client serializers/deserializers
+= Validating schemas using Kafka client serializers/deserializers
 //If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
 
 {registry} provides Kafka client serializers/deserializers for producer and consumer applications. Kafka producer applications use serializers to encode messages that conform to a specific event schema. Kafka consumer applications use deserializers to validate that the messages have been serialized using the correct schema, based on a specific schema ID. This ensures consistent schema use and helps to prevent data errors at runtime.
 
-This chapter provides instructions on how to use the Kafka client serializer and deserializer for Apache Avro in your Kafka producer and consumer client applications:
+This chapter provides instructions on how to use the Kafka client serializers and deserializers for Apache Avro, JSON Schema, and Google Protobuf in your Kafka producer and consumer client applications:
 
 * xref:registry-serdes-concepts-serde-{context}[]
 * xref:registry-serdes-types-serde-{context}[]

diff --git a/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc b/docs/modules/ROOT/pages/getting-started/assembly-using-the-registry-client.adoc
@@ -2,13 +2,13 @@
 include::{mod-loc}shared/all-attributes.adoc[]
 
 [id="using-the-registry-client"]
-= Using the {registry} Java client
+= Managing {registry} content using the Java client
 
 This chapter explains how to use the {registry} Java client:
 
 * xref:registry-client-intro[]
 * xref:writing-registry-client[]
-* xref:registry-client-types[]
+* xref:registry-client-config[]
 
 //INCLUDES
 include::{mod-loc}getting-started/con-registry-client.adoc[leveloffset=+1]

diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -1,6 +1,21 @@
 include::partial$shared/attributes.adoc[]
 
-= Welcome
+= {registry} documentation
 
-Welcome to the {registry} version {registry-version} documentation.
-Navigate using the left hand menu.
+Welcome to the {registry} version {registry-version} documentation. Navigate using the left menu.
+
+{registry} stores and retrieves API designs and event schemas, and gives you control of their evolution.
+
+
+== About this documentation
+This introduces {registry}, explains how to install with your chosen storage option, and how to manage event schemas and API designs using the {registry} web console, REST API, Maven plug-in, or Java client. 
+
+This also explains how to enforce schemas using Kafka client serializers and deserializers in your consumer and producer applications. It also describes {registry} content types and rule types, and OpenShift environment variables for health checks.
+
+== Getting help with {registry} 
+
+See the link:https://github.com/Apicurio/apicurio-registry[{registry}] and https://github.com/Apicurio/apicurio-registry-operator[{registry} Operator] projects on GitHub.
+Any contributions, suggestions, and issue reports are welcome.
+
+ifdef::apicurio-registry[]
+link:https://github.com/Apicurio/apicurio-registry/issues/new[Create an issue] on GitHub if you find any problems.
diff --git a/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc b/docs/modules/ROOT/partials/getting-started/con-kafka-connect-converters.adoc
@@ -2,7 +2,7 @@
 
 
 [id="kafka-connect"]
-= Kafka Connect converters 
+= Stream data to external sytems with Kafka Connect converters 
 You can use {registry} with Apache Kafka Connect to stream data between Kafka and external systems. Using Kafka Connect, you can define connectors for different systems to move large volumes of data into and out of Kafka-based systems. 
 
 .{registry} and Kafka Connect architecture

diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-artifact-metadata.adoc
diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-artifacts.adoc
@@ -1,7 +1,7 @@
 // Metadata created by nebel
 
 [id="registry-artifacts"]
-= {registry} artifacts
+= Store schema and API artifacts in {registry} 
 
 The items stored in {registry}, such as event schemas and API specifications, are known as registry _artifacts_. The following shows an example of an Apache Avro schema artifact in JSON format for a simple share price application:
 
@@ -26,4 +26,4 @@ The items stored in {registry}, such as event schemas and API specifications, ar
 
 When a schema or API contract is added as an artifact in the registry, client applications can then use that schema or API contract to validate that client messages conform to the correct data structure at runtime. 
 
-{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google protocol buffers, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see {registry-artifact-types}.
+{registry} supports a wide range of message payload formats for standard event schemas and API specifications. For example, supported formats include Apache Avro, Google protocol buffers, GraphQL, AsyncAPI, OpenAPI, and others. For more details, see {registry-reference}.
diff --git a/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc b/docs/modules/ROOT/partials/getting-started/con-registry-client.adoc
@@ -1,24 +1,10 @@
 // Metadata created by nebel
 
 [id="registry-client-intro"]
-= {registry} Java client overview
+= {registry} Java client 
 
-You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored 
-in the registry using the {registry} Java client classes.
+You can manage artifacts stored in {registry} using a Java client application. You can create, read, update, or delete artifacts stored in the registry using the {registry} Java client classes.
 
-You can access the {registry} Java client by adding the proper dependency to your project, see xref:writing-registry-client[].
+You can access the {registry} Java client by adding the correct dependency to your project, see xref:writing-registry-client[].
 
-The {registry} client is autocloseable and is implemented using Retrofit and OkHttp as base libraries. This gives the user the ability to customize its
-usage by, for example, adding custom headers or enabling TLS auth support.
-
-== Enabling TLS support in the client
-
-You can configure TLS authentication using the following properties:
-
-* apicurio.registry.request.ssl.truststore.location
-* apicurio.registry.request.ssl.truststore.password
-* apicurio.registry.request.ssl.truststore.type
-* apicurio.registry.request.ssl.keystore.location
-* apicurio.registry.request.ssl.keystore.password
-* apicurio.registry.request.ssl.keystore.type
-* apicurio.registry.request.ssl.key.password
+The {registry} client is auto-closeable and is implemented using Retrofit and OkHttp as base libraries. This gives you the ability to customize its use, for example, by adding custom headers or enabling Transport Layer Security (TLS) authentication. For more details, see xref:registry-client-config[].