Skip to content

Commit

Permalink
clean up registry user docs and restructure (#1004)
Browse files Browse the repository at this point in the history
  • Loading branch information
smccarthy-ie authored Nov 11, 2020
1 parent e4d1588 commit baf90b6
Showing 37 changed files with 360 additions and 369 deletions.
6 changes: 3 additions & 3 deletions docs/local-test-playbook.yml
Original file line number Diff line number Diff line change
@@ -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]
2 changes: 1 addition & 1 deletion docs/modules/ROOT/assets/attachments/registry-rest-api.htm
Original file line number Diff line number Diff line change
@@ -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>
7 changes: 4 additions & 3 deletions docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
@@ -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[]
Original file line number Diff line number Diff line change
@@ -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:

Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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]
Original file line number Diff line number Diff line change
@@ -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}[]
Original file line number Diff line number Diff line change
@@ -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]
21 changes: 18 additions & 3 deletions docs/modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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

This file was deleted.

Original file line number Diff line number Diff line change
@@ -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}.
Original file line number Diff line number Diff line change
@@ -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[].
Loading

0 comments on commit baf90b6

Please sign in to comment.