Red Hat Summit Red Hat Summit지원콘솔개발자평가판 시작연락처

이 콘텐츠는 선택한 언어로 제공되지 않습니다.

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

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

Prerequisites

  • Apicurio 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

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/v3</registryUrl> 2
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
            <clientScope>MY-CLIENT-SCOPE</clientScope>
            <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
                    <artifactType>GRAPHQL</artifactType>
                    <file>${project.basedir}/src/main/resources/apis/example.graphql</file>
                    <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                    <canonicalize>true</canonicalize>
                </artifact>
            </artifacts>
        </configuration>
    </execution>
  </executions>
 </plugin>
    1
    Specify register as the execution goal to upload the schema artifact to Apicurio Registry.
    2
    Specify the Apicurio Registry URL with the ../apis/registry/v3 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Apicurio 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.

Additional resources

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

You can use the Maven plug-in to download artifacts from Apicurio 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/v3</registryUrl> 2
          <authServerUrl>MY-AUTH-SERVER</authServerUrl>
          <clientId>MY-CLIENT-ID</clientId>
          <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
          <clientScope>MY-CLIENT-SCOPE</clientScope>
          <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>
    1
    Specify download as the execution goal.
    2
    Specify the Apicurio Registry URL with the ../apis/registry/v3 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Apicurio 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.

Additional resources

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

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 Apicurio 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 Apicurio 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/v3</registryUrl> 2
            <authServerUrl>MY-AUTH-SERVER</authServerUrl>
            <clientId>MY-CLIENT-ID</clientId>
            <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
            <clientScope>MY-CLIENT-SCOPE</clientScope>
            <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>
    1
    Specify test-update as the execution goal to test the schema artifact.
    2
    Specify the Apicurio Registry URL with the ../apis/registry/v3 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Apicurio 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.

Additional resources

5.4. Adding artifact references manually using the Apicurio Registry Maven plug-in

Some Apicurio Registry artifact types 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.

The following artifact types support artifact references:

  • Apache Avro
  • Google Protobuf
  • JSON Schema
  • OpenAPI
  • AsyncAPI

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

Exchange schema

{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}

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"
    }
  ]
}

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 Apicurio 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/v3</registryUrl> 2
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                <clientScope>MY-CLIENT-SCOPE</clientScope>
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId> 4
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <artifactType>AVRO</artifactType>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc
                        </file>
                        <ifExists>FIND_OR_CREATE_VERSION</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>
                                <artifactType>AVRO</artifactType>
                                <file>
                                    ${project.basedir}/src/main/resources/schemas/Exchange.avsc
                                </file>
                                <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                                <canonicalize>true</canonicalize>
                            </reference>
                        </references>
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
    1
    Specify register as the execution goal to upload the schema artifacts to Apicurio Registry.
    2
    Specify the Apicurio Registry URL by using the ../apis/registry/v3 endpoint.
    3
    If authentication is required, you can specify your authentication server and client credentials.
    4
    Specify the Apicurio Registry artifact group ID. You can specify the default group if you do not want to use a unique group ID.
    5
    Specify the Apicurio 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.

Additional resources

5.5. Adding artifact references automatically using the Apicurio Registry Maven plug-in

Some Apicurio Registry artifact types 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.

The following artifact types support artifact references:

  • Apache Avro
  • Google Protobuf
  • JSON Schema
  • OpenAPI
  • AsyncAPI

You can specify a single artifact and configure the Apicurio Registry Maven plugin to automatically detect all references to artifacts located in the same directory, and to automatically register those references. This is a Technology Preview feature.

Important

Technology Preview features are not supported with RedHat production service level agreements (SLAs) and might not be functionally complete. RedHat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of RedHat Technology Preview features, see Technology Preview Features Support Scope.

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"
    }
  ]
}

Exchange schema

{
  "namespace": "com.kubetrade.schema.common",
  "type": "enum",
  "name": "Exchange",
  "symbols" : ["GEMINI"]
}

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/v3</registryUrl> 2
                <authServerUrl>MY-AUTH-SERVER</authServerUrl>
                <clientId>MY-CLIENT-ID</clientId>
                <clientSecret>MY-CLIENT-SECRET</clientSecret> 3
                <clientScope>MY-CLIENT-SCOPE</clientScope>
                <artifacts>
                    <artifact>
                        <groupId>test-group</groupId> 4
                        <artifactId>TradeKey</artifactId>
                        <version>2.0</version>
                        <artifactType>AVRO</artifactType>
                        <file>
                            ${project.basedir}/src/main/resources/schemas/TradeKey.avsc 5
                        </file>
                        <ifExists>FIND_OR_CREATE_VERSION</ifExists>
                        <canonicalize>true</canonicalize>
                        <autoRefs>true</autoRefs> 6
                    </artifact>
                </artifacts>
            </configuration>
        </execution>
    </executions>
</plugin>
    1
    Specify register as the execution goal to upload the schema artifacts to Apicurio Registry.
    2
    Specify the Apicurio Registry URL by using the ../apis/registry/v3 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 <autoRefs> 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.

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

© 2024 Red Hat, Inc.