Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

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

This chapter explains how to manage schema and API artifacts stored in the registry using the Service Registry Maven plug-in:

Prerequisites

5.1. Adding schema and API artifacts using the Maven plug-in
Copiar o link

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

Prerequisites

  • Service Registry is installed and running in your environment

Procedure

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 the 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.

5.2. Downloading schema and API artifacts using the Maven plug-in
Copiar o link

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

  • Service Registry is installed and running in your environment

Procedure

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.

5.3. Adding artifact references using the Service Registry Maven plug-in
Copiar o link

Service Registry artifact types such as Apache Avro, Protobuf, and JSON Schema can include artifact references from one artifact file to another. You can create efficiencies by defining reusable schema and 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 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 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

  • Service Registry is installed and running in your environment
  • The Exchange schema artifact is already created in Service Registry

Procedure

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>
            <id>register-artifact</id>
            <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 artifact to the 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. 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.

5.4. Testing schema and API artifacts using the Maven plug-in
Copiar o link

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

  • Service Registry must be installed and running in your environment

Procedure

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>
                <artifact>
                    <groupId>TestGroup</groupId>
                    <artifactId>ExampleAPI</artifactId>
                    <type>GRAPHQL</type>
                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                </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.
Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat