Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 5. Managing Service Registry content using the Maven plug-in

When developing client applications, you can use the Service Registry Maven plug-in to manage schema and API artifacts stored in Service Registry:

Prerequisites

  • Service Registry is installed and running in your environment.
  • Apache Maven is installed and configured in your environment.

5.1. Adding schema and API artifacts using the Maven plug-in
Copia collegamento

The most common use case for the Maven plug-in is adding artifacts during a build of your client application. You can accomplish this by using the register execution goal.

Prerequisites

Procedure

  1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register an artifact. The following example shows registering Apache Avro and GraphQL schemas: 

    <plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
            <goal>register</goal>
    1 
    
        </goals>
        <configuration>
            <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl>
    2 
    
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret>
    3 
    
            <artifacts>
                <artifact>
                    <groupId>TestGroup</groupId>
    4 
    
                    <artifactId>FullNameRecord</artifactId>
                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
                    <ifExists>FAIL</ifExists>
                </artifact>
                <artifact>
                    <groupId>TestGroup</groupId>
                    <artifactId>ExampleAPI</artifactId>
    5 
    
                    <type>GRAPHQL</type>
                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                    <ifExists>RETURN_OR_UPDATE</ifExists>
                    <canonicalize>true</canonicalize>
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>
    Copy to Clipboard Toggle word wrap
    1
    Specify register as the execution goal to upload the schema artifact to Service Registry.
    2
    Specify the Service Registry URL with the ../apis/registry/v2 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Service Registry artifact group ID. You can specify the default group if you do not want to use a unique group ID.
    5
    You can register multiple artifacts using the specified group ID, artifact ID, and location.
  2. Build your Maven project, for example, by using the mvn package command.

5.2. Downloading schema and API artifacts using the Maven plug-in
Copia collegamento

You can use the Maven plug-in to download artifacts from Service Registry. This is often useful, for example, when generating code from a registered schema.

Prerequisites

Procedure

  1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to download an artifact. The following example shows downloading Apache Avro and GraphQL schemas. 

    <plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>download</goal>
    1 
    
      </goals>
      <configuration>
          <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl>
    2 
    
          <authServerUrl>MY-AUTH-SERVER</authServerUrl>
          <clientId>MY-CLIENT-ID</clientId>
          <clientSecret>MY-CLIENT-SECRET</clientSecret>
    3 
    
          <artifacts>
              <artifact>
                  <groupId>TestGroup</groupId>
    4 
    
                  <artifactId>FullNameRecord</artifactId>
    5 
    
                  <file>${project.build.directory}/classes/record.avsc</file>
                  <overwrite>true</overwrite>
              </artifact>
              <artifact>
                  <groupId>TestGroup</groupId>
                  <artifactId>ExampleAPI</artifactId>
                  <version>1</version>
                  <file>${project.build.directory}/classes/example.graphql</file>
                  <overwrite>true</overwrite>
              </artifact>
          </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>
    Copy to Clipboard Toggle word wrap
    1
    Specify download as the execution goal.
    2
    Specify the Service Registry URL with the ../apis/registry/v2 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Service Registry artifact group ID. You can specify the default group if you do not want to use a unique group.
    5
    You can download multiple artifacts to a specified directory using the artifact ID.
  2. Build your Maven project, for example, by using the mvn package command.

5.3. Testing schema and API artifacts using the Maven plug-in
Copia collegamento

You might want to verify that an artifact can be registered without actually making any changes. This is often useful when rules are configured in Service Registry. Testing the artifact results in a failure if the artifact content violates any of the configured rules.

Note

When testing artifacts using the Maven plug-in, even if the artifact passes the test, no content is added to Service Registry.

Prerequisites

Procedure

  1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to test an artifact. The following example shows testing an Apache Avro schema: 

    <plugin>
  <groupId>io.apicurio</groupId>
  <artifactId>apicurio-registry-maven-plugin</artifactId>
  <version>${apicurio.version}</version>
  <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
            <goal>test-update</goal>
    1 
    
        </goals>
        <configuration>
            <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl>
    2 
    
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret>
    3 
    
            <artifacts>
                <artifact>
                    <groupId>TestGroup</groupId>
    4 
    
                    <artifactId>FullNameRecord</artifactId>
                    <file>${project.basedir}/src/main/resources/schemas/record.avsc</file>
    5 
    
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>
    Copy to Clipboard Toggle word wrap
    1
    Specify test-update as the execution goal to test the schema artifact.
    2
    Specify the Service Registry URL with the ../apis/registry/v2 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Service Registry artifact group ID. You can specify the default group if you do not want to use a unique group.
    5
    You can test multiple artifacts from a specified directory using the artifact ID.
  2. Build your Maven project, for example, by using the mvn package command.

Service Registry artifact types such as Apache Avro, Google Protobuf, and JSON Schema can include artifact references from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references.

This section shows a simple example of using the Service Registry Maven plug-in to manually register an artifact reference to a simple Avro schema artifact stored in Service Registry. This example assumes that the following Exchange schema artifact has already been created in Service Registry:

Exchange schema

{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}
Copy to Clipboard Toggle word wrap

This example then creates a TradeKey schema artifact, which includes a reference to the nested Exchange schema artifact:

TradeKey schema with nested reference to Exchange schema

{
  "namespace": "com.kubetrade.schema.trade",
  "type": "record",
  "name": "TradeKey",
  "fields": [
    {
      "name": "exchange",
      "type": "com.kubetrade.schema.common.Exchange"
    },
    {
      "name": "key",
      "type": "string"
    }
  ]
}
Copy to Clipboard Toggle word wrap

Prerequisites

  • You have created a Maven project for your client application. For more details, see the Apache Maven documentation.
  • The referenced Exchange schema artifact is already created in Service Registry.

Procedure

  1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register the TradeKey schema, which includes a nested reference to the Exchange schema as follows: 

    <plugin>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-maven-plugin</artifactId>
    <version>${apicurio-registry.version}</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>register</goal>
    1 
    
            </goals>
            <configuration>
                <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl>
    2 
    
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret>
    3 
    
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId>
    4 
    
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <type>AVRO</type>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                        </file>
                        <ifExists>RETURN_OR_UPDATE</ifExists>
                        <canonicalize>true</canonicalize>
                        <references>
                            <reference>
    5 
    
                                <name>com.kubetrade.schema.common.Exchange</name>
                                <groupId>test-group</groupId>
                                <artifactId>Exchange</artifactId>
                                <version>2.0</version>
                                <type>AVRO</type>
                                <file>
                                    ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                </file>
                                <ifExists>RETURN_OR_UPDATE</ifExists>
                                <canonicalize>true</canonicalize>
                            </reference>
                        </references>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
    Copy to Clipboard Toggle word wrap
    1
    Specify register as the execution goal to upload the schema artifacts to Service Registry.
    2
    Specify the Service Registry URL by using the ../apis/registry/v2 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Service Registry artifact group ID. You can specify the default group if you do not want to use a unique group ID.
    5
    Specify the Service Registry artifact reference using its group ID, artifact ID, version, type, and location. You can register multiple artifact references in this way.
  2. Build your Maven project, for example, by using the mvn package command.

Service Registry artifact types such as Apache Avro, Google Protobuf, and JSON Schema can include artifact references from one artifact file to another. You can create efficiencies by defining reusable schema or API artifacts, and then referencing them from multiple locations in artifact references.

You can specify a single artifact and configure the Service Registry Maven plugin to automatically detect all references to artifacts located in the same directory, and to automatically register those references.

This section shows a simple example of using the Maven plug-in to register an Avro schema and automatically detect and register an artifact reference to a simple schema artifact. This example assumes that the parent TradeKey artifact and the nested Exchange schema artifact are both available in the same directory:

TradeKey schema with nested reference to Exchange schema

{
  "namespace": "com.kubetrade.schema.trade",
  "type": "record",
  "name": "TradeKey",
  "fields": [
    {
      "name": "exchange",
      "type": "com.kubetrade.schema.common.Exchange"
    },
    {
      "name": "key",
      "type": "string"
    }
  ]
}
Copy to Clipboard Toggle word wrap

Exchange schema

{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}
Copy to Clipboard Toggle word wrap

Prerequisites

  • You have created a Maven project for your client application. For more details, see the Apache Maven documentation.
  • The TradeKey schema artifact and the nested Exchange schema artifact files are both located in the same directory.

Procedure

  1. Update your Maven pom.xml file to use the apicurio-registry-maven-plugin to register the TradeKey schema, which includes a nested reference to the Exchange schema as follows: 

    <plugin>
    <groupId>io.apicurio</groupId>
    <artifactId>apicurio-registry-maven-plugin</artifactId>
    <version>${apicurio-registry.version}</version>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>register</goal>
    1 
    
            </goals>
            <configuration>
                <registryUrl>MY-REGISTRY-URL/apis/registry/v2</registryUrl>
    2 
    
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret>
    3 
    
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId>
    4 
    
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <type>AVRO</type>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
    5 
    
                        </file>
                        <ifExists>RETURN_OR_UPDATE</ifExists>
                        <canonicalize>true</canonicalize>
                        <analyzeDirectory>true</analyzeDirectory>
    6 
    
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
    Copy to Clipboard Toggle word wrap
    1
    Specify register as the execution goal to upload the schema artifacts to Service Registry.
    2
    Specify the Service Registry URL by using the ../apis/registry/v2 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the parent artifact group ID that contains the references. You can specify the default group if you do not want to use a unique group ID.
    5
    Specify the location of the parent artifact file. All referenced artifacts must also be located in the same directory.
    6
    Set the <analyzeDirectory> option to true to automatically detect and register all references to artifacts in the same directory. You can register multiple artifact references in this way.
  2. Build your Maven project, for example, by using the mvn package command.
Torna in cima
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2025 Red Hat