Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix duplications #3575

Merged
merged 8 commits into from
Apr 2, 2024
Merged

Fix duplications #3575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e985098
fix duplications
janan07 Mar 28, 2024
f20863c
Merge branch 'master' into janan07-duplication-fixes
janan07 Mar 28, 2024
a4fb683
Merge branch 'master' into janan07-duplication-fixes
janan07 Mar 28, 2024
0806352
Merge branch 'master' into janan07-duplication-fixes
janan07 Mar 28, 2024
5386cd2
Merge branch 'master' into janan07-duplication-fixes
janan07 Apr 2, 2024
650f9df
fix links/formatting
janan07 Apr 2, 2024
f1b635b
Merge branch 'janan07-duplication-fixes' of https://github.com/zowe/d…
janan07 Apr 2, 2024
ad9ddd4
fix links/improve formatting
janan07 Apr 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 37 additions & 32 deletions docs/extend/extend-apiml/onboard-plain-java-enabler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

This article is part of a series of onboarding guides, which outline the process of onboarding REST API services to the Zowe API Mediation Layer (API ML). As a service developer, you can onboard a REST service with the API ML with the Zowe API Mediation Layer using our Plain Java Enabler (PJE). This enabler is built without a dependency on Spring Cloud, Spring Boot, or SpringFramework.

**Tip:** For more information about onboarding API services with the API ML, see the [Onboarding Overview](onboard-overview.md).
:::tip
For more information about onboarding API services with the API ML, see the [Onboarding Overview](onboard-overview.md).
:::

## Introduction

Expand All @@ -21,8 +23,10 @@ The PJE library serves the needs of Java developers who are not using either [Sp

Additionally, this enabler is not intended for use in projects that depend on [Spring Cloud Netflix](https://spring.io/projects/spring-cloud-netflix) components. Configuration settings in the PJE and Spring Cloud Netflix Eureka Client are different. Using the two configuration settings in combination makes the result state of the discovery registry unpredictable.

**Tip:** For more information about how to utilize another API ML enablers, see the documentation in
:::tip
For more information about how to utilize another API ML enablers, see the documentation in
the [Onboarding Overview](onboard-overview.md).
:::

## Onboarding your REST service with API ML

Expand Down Expand Up @@ -60,19 +64,22 @@ Ensure that the prerequisites from the [Onboarding Overview](onboard-overview.md
* The REST API service to onboard is written in Java
* The service is enabled to communicate with API ML Discovery Service over a TLS v1.2 secured connection

**Notes:**
:::noteNotes:

* This documentation is valid for API ML version `ZoweApimlVersion 1.3.0` and higher. We recommend that you check the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for latest stable versions.
* This documentation is valid for API ML version `ZoweApimlVersion 1.3.0` and higher. We recommend that you check the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for the latest stable versions.

* Following this guide enables REST services to be deployed on a z/OS environment. Deployment to a z/OS environment, however, is not required. As such, you can first develop on a local machine before you deploy on z/OS.

* The API Mediation Layer provides the sample application using the Plain Java Enabler in the [api-layer repository](https://github.com/zowe/api-layer/tree/v2.x.x/onboarding-enabler-java-sample-app)
:::

## Configuring your project

Use either _Gradle_ or _Maven_ build automation systems to configure the project with the service to be onboarded. Use the appropriate configuration procedure that corresponds to your build automation system.

**Note:** You can use either the Zowe Artifactory or an artifactory of your choice. If you decide to build the API ML from source, you are required to publish the enabler artifact to your artifactory. Publish the enabler artifact by using the _Gradle_ tasks provided in the source code.
:::note
You can use either the Zowe Artifactory or an artifactory of your choice. If you decide to build the API ML from source, you are required to publish the enabler artifact to your artifactory. Publish the enabler artifact by using the _Gradle_ tasks provided in the source code.
:::

### Gradle build automation system
Use the following procedure to use _Gradle_ as your build automation system.
Expand Down Expand Up @@ -165,7 +172,9 @@ Use the following procedure if you use _Maven_ as your build automation system.

To configure your service, create the configuration file `service-configuration.yml` in your service source tree resources directory. The default path for a java application is `src/main/resources`. The `service-configuration.yml` file is used to set the application properties and eureka metadata. Application properties are for your service runtime. For example, the `ssl` section specifies the keystore and trustore. The eureka metadata is used for registration with API Mediation Layer.

**Note:** To externalize service onboarding configuration, see: [Externalizing onboarding configuration](onboard-plain-java-enabler-external-configuration.md).
:::note
To externalize service onboarding configuration, see: [Externalizing onboarding configuration](onboard-plain-java-enabler-external-configuration.md).
:::

The following code snippet shows an example of `service-configuration.yml`. Some parameters which are specific for your service deployment
are in `${parameterValue}` format. For your service configuration file, provide actual values or externalize your onboarding configuration.
Expand Down Expand Up @@ -323,11 +332,9 @@ statusPageRelativeUrl: /application/info
healthCheckRelativeUrl: /application/health
```

where:

* **homePageRelativeUrl**

specifies the relative path to the home page of your service.
Specifies the relative path to the home page of your service.

Start this path with `/`. If your service has no home page, leave this parameter blank.

Expand All @@ -338,7 +345,7 @@ where:

* **statusPageRelativeUrl**

specifies the relative path to the status page of your service.
Specifies the relative path to the status page of your service.

Start this path with `/`.

Expand All @@ -351,7 +358,7 @@ where:

* **healthCheckRelativeUrl**

specifies the relative path to the health check endpoint of your service.
Specifies the relative path to the health check endpoint of your service.

Start this path with `/`.

Expand Down Expand Up @@ -387,18 +394,17 @@ apiInfo:
console.log('hello');
```

where:
* **apiInfo.apiId**

specifies the API identifier that is registered in the API ML installation.
Specifies the API identifier that is registered in the API ML installation.
The API ID uniquely identifies the API in the API ML.
The `apiId` can be used to locate the same APIs that are provided by different service instances. The API developer defines this ID.
The `apiId` must be a string of up to 64 characters
that uses lowercase alphanumeric characters and a dot: `.` .

* **apiInfo.version**

specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API.
Specifies the api `version`. This parameter is used to correctly retrieve the API documentation according to requested version of the API.

* **apiInfo.gatewayUrl**

Expand All @@ -407,20 +413,20 @@ where:

* **apiInfo.swaggerUrl** (Optional)

specifies the Http or Https address where the Swagger JSON document is available.
Specifies the Http or Https address where the Swagger JSON document is available.

* **apiInfo.documentationUrl** (Optional)

specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation.
Specifies the link to the external documentation. A link to the external documentation can be included along with the Swagger documentation.

* **apiInfo.defaultApi** (Optional)

specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one
Specifies that this API is the default one shown in the API Catalog. If no apiInfo fields have `defaultApi` set to `true`, the default API is the one
with the highest API `version`.

* **apiInfo.codeSnippet** (Optional)

specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing
Specifies the customized code snippet for a specific endpoint (API operation). The snippet is displayed in the API Catalog under the specified operation, after executing
the request using the *Try it out* functionality.
When specifying this configuration, you need to provide the following parameters:
* **`endpoint`**
Expand Down Expand Up @@ -449,11 +455,10 @@ routes:
- gatewayUrl: api/v1/api-doc
serviceUrl: /sampleservice-api/api-doc
```
where:

* **routes**

specifies the container element for the route.
Specifies the container element for the route.

* **routes.gatewayUrl**

Expand Down Expand Up @@ -510,23 +515,21 @@ The following code block is an example of configuration of a service tile in the
version: 1.0.0
```

where:

* **catalog.tile.id**

specifies the unique identifier for the product family of API services.
Specifies the unique identifier for the product family of API services.
This is a value used by the API ML to group multiple API services into a single tile.
Each unique identifier represents a single API dashboard tile in the Catalog.

**Tip:** Specify a value that does not interfere with API services from other products. We recommend that you use your company and product name as part of the ID.

* **catalog.tile.title**

specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title.
Specifies the title of the product family of the API service. This value is displayed in the API Catalog dashboard as the tile title.

* **catalog.tile.description**

is the detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description.
The detailed description of the API services product family. This value is displayed in the API Catalog UI dashboard as the tile description.

* **catalog.tile.version**

Expand Down Expand Up @@ -639,8 +642,6 @@ discoveryServiceUrls:
- http://......
```

where:

* **discoveryServiceUrls**

Specifies the public URL of the Discovery Service. The system administrator at the customer site defines this parameter.
Expand Down Expand Up @@ -826,11 +827,15 @@ Once you are able to build and start your service successfully, you can use the

Specific addresses and user credentials for the individual API ML components depend on your target runtime environment.

**Note:** If you are working with local installation of API ML and you are using our dummy identity provider, enter `user`
:::note
If you are working with local installation of API ML and you are using our dummy identity provider, enter `user`
for both `username` and `password`. If API ML was installed by system administrators, ask them to provide you
with actual addresses of API ML components and the respective user credentials.
:::

**Tip:** Wait for the Discovery Service to discover your service. This process may take a few minutes after your service was successfully started.
:::tip
Wait for the Discovery Service to discover your service. This process may take a few minutes after your service was successfully started.
:::

## Troubleshooting

Expand All @@ -847,13 +852,13 @@ Some logging frameworks provide other tools to suppress repeated messages. Consu

**Example:**

The Logback framework provides a filter tool, [DuplicateMessageFilter](http://logback.qos.ch/manual/filters.html#DuplicateMessageFilter).

Add the following code to your configuration file if you use XML configuration:
```
<turboFilter class="ch.qos.logback.classic.turbo.DuplicateMessageFilter">
<AllowedRepetitions>0</AllowedRepetitions>
</turboFilter>
```

**Note:** For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.
:::note
For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.
:::
46 changes: 32 additions & 14 deletions docs/extend/extend-apiml/onboard-spring-boot-enabler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@
This guide is part of a series of guides to onboard a REST API service with the Zowe API Mediation Layer.
As an API developer, you can onboard your REST API service built with the Spring Boot framework with the Zowe API Mediation Layer.

**Note:** Before API ML version 1.2, the API ML provided an integration enabler based on Spring Cloud Netflix components. From version 1.3 and later, the API ML uses a new implementation based on the Plain Java Enabler (PJE) that is not backwards compatible with the previous enabler versions. API ML core services (Discovery Service, Gateway, and API Catalog) support both the old and new enabler versions.
:::note
Before API ML version 1.2, the API ML provided an integration enabler based on Spring Cloud Netflix components. From version 1.3 and later, the API ML uses a new implementation based on the Plain Java Enabler (PJE) that is not backwards compatible with the previous enabler versions. API ML core services (Discovery Service, Gateway, and API Catalog) support both the old and new enabler versions.
:::

**Tip:** For more information about how to utilize another onboarding method, see:
:::tip
For more information about how to utilize another onboarding method, see:

* [Onboard a REST API service with the Plain Java Enabler (PJE)](onboard-plain-java-enabler.md)
* [Onboard a REST service directly calling eureka with xml configuration](onboard-direct-eureka-call.md)
* [Onboard an existing REST API service without code changes](onboard-static-definition.md)
:::

## Outline of onboarding a REST service using Spring Boot

Expand Down Expand Up @@ -50,13 +54,17 @@ Add a dependency on the Spring Enabler version to your project build configurati
* onboarding-enabler-spring-v1
* onboarding-enabler-spring-v2

**Note:** The process of onboarding an API service is the same for both Spring Boot enabler versions.
:::note
The process of onboarding an API service is the same for both Spring Boot enabler versions.
:::

## Configuring your project

Use either _Gradle_ or _Maven_ as your build automation system to manage your project builds.

**Note:** You can download the selected enabler artifact from the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for latest stable versions.. Alternatively, if you decide to build the API ML from source, it is necessary to publish the enabler artifact to your Artifactory. Publish the enabler artifact by using the _Gradle_ tasks provided in the source code.
:::note
You can download the selected enabler artifact from the [Zowe Artifactory](https://zowe.jfrog.io/zowe/libs-release/org/zowe/apiml/sdk/onboarding-enabler-java/) for latest stable versions.. Alternatively, if you decide to build the API ML from source, it is necessary to publish the enabler artifact to your Artifactory. Publish the enabler artifact by using the _Gradle_ tasks provided in the source code.
:::

### Gradle build automation system
Use the following procedure to use _Gradle_ as your build automation system.
Expand Down Expand Up @@ -310,8 +318,10 @@ A property notation provided in the format `-Dproperty.key=PROPERTY_VALUE` can b
key: PROPERTY_VALUE
```

**Note**: System properties provided with `-D` notation on the command line will not replace properties defined
:::note
System properties provided with `-D` notation on the command line will not replace properties defined
in any of the YAML configuration files.
:::

### Authentication properties
These parameters are not required. If a parameter is not specified, a default value is used. See [Authentication Parameters for Onboarding REST API Services](./authentication-for-apiml-services.md#authentication-parameters) for more details.
Expand Down Expand Up @@ -409,14 +419,16 @@ apiml:
# and other properties
```

**Tip:** To determine if your configuration is complete, set the logging level to `debug` and run your application. Setting the logging level to 'debug' enables you to troubleshoot issues with certificates for HTTPS and connections with other services.
:::tip
To determine if your configuration is complete, set the logging level to `debug` and run your application. Setting the logging level to 'debug' enables you to troubleshoot issues with certificates for HTTPS and connections with other services.

```yaml
logging:
level:
ROOT: INFO
org.zowe.apiml: DEBUG
```
:::

3. Provide the suitable parameter corresponding to your runtime environment:

Expand Down Expand Up @@ -567,8 +579,10 @@ Use the following procedure to add Swagger API documentation to your project.
3. Customize this configuration according to your specifications. For more information about customization properties,
see [Springfox documentation](https://springfox.github.io/springfox/docs/snapshot/#configuring-springfox).

**Note:** The current SpringFox Version 2.9.2 does not support OpenAPI 3.0.
For more information about the open feature request see this [issue](https://github.com/springfox/springfox/issues/2022).
:::note
The current SpringFox Version 2.9.2 does not support OpenAPI 3.0.
For more information about the open feature request see this [issue](https://github.com/springfox/springfox/issues/2022).
:::

## Validating the discoverability of your API service by the Discovery Service

Expand All @@ -583,12 +597,15 @@ Once you build and start your service successfully, you can use the option of va

Specific addresses and user credentials for the individual API ML components depend on your target runtime environment.

**Note:** If you are working with local installation of API ML and you are using our dummy identity provider, enter `user`
:::note
If you are working with local installation of API ML and you are using our dummy identity provider, enter `user`
for both `username` and `password`. If API ML was installed by system administrators, ask them to provide you
with actual addresses of API ML components and the respective user credentials.
:::

**Tip:** Wait for the Discovery Service to fully register your service. This process may take a few minutes after your
service was successfully started.
:::tip
Wait for the Discovery Service to fully register your service. This process may take a few minutes after your service was successfully started.
:::


## Troubleshooting
Expand All @@ -607,13 +624,14 @@ Some logging frameworks provide other tools to suppress repeated messages. Consu

**Example:**

The Logback framework provides a filter tool, [DuplicateMessageFilter](http://logback.qos.ch/manual/filters.html#DuplicateMessageFilter).

Add the following code to your configuration file if you use XML configuration:

```
<turboFilter class="ch.qos.logback.classic.turbo.DuplicateMessageFilter">
<AllowedRepetitions>0</AllowedRepetitions>
</turboFilter>
```
**Note:** For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.

:::note
For more information, see the [full configuration used in the Core Services](https://github.com/zowe/api-layer/blob/master/apiml-common/src/main/resources/logback.xml) in GitHub.
:::
3 changes: 0 additions & 3 deletions docs/user-guide/configure-certificates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,6 @@ The host communicating with a certificate should have its hostname match one of
### z/OSMF access
The z/OSMF certificate is verified according to Zowe's [Certificate verification setting](#certificate-verification), as is the case with any certificate that is seen by Zowe. However, Zowe will also set up a trust relationship with z/OSMF within Zowe's truststore during certificate setup automation if the certificate setting is set to any value other than [DISABLED](#disabled-verification).

The host communicating with a certificate should have its hostname match one of the values of the certificate's Common Name or Subject Alternate Name (SAN). If this condition is not true for at least one of the certificates seen by Zowe, then you may wish to set [NON-STRICT verification](#non-strict-verification) within Zowe configuration.


## Certificate setup type
Whether importing or letting Zowe generate certificates, the setup for Zowe certificate automation and the configuration to use an existing keystore and truststore depends upon the content format: file-based (`PKCS12`) or z/OS key ring-based.

Expand Down
Loading
Loading