From e9850988829db6f3b9f3721d316638b762b1ba4b Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Thu, 28 Mar 2024 13:49:47 +0100 Subject: [PATCH 1/3] fix duplications Signed-off-by: Andrew Jandacek --- docs/user-guide/configure-certificates.md | 3 --- sidebars.js | 3 +-- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/user-guide/configure-certificates.md b/docs/user-guide/configure-certificates.md index c3c0490b6d..beed74eb5f 100644 --- a/docs/user-guide/configure-certificates.md +++ b/docs/user-guide/configure-certificates.md @@ -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. diff --git a/sidebars.js b/sidebars.js index 5385cfb121..55358715e4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -287,8 +287,7 @@ module.exports = { "items": [ "extend/extend-apiml/api-mediation-infinispan", "extend/extend-apiml/api-mediation-vsam", - "extend/extend-apiml/api-mediation-redis", - "extend/extend-apiml/api-mediation-infinispan" + "extend/extend-apiml/api-mediation-redis" ] }, "user-guide/api-mediation/configuration-customizing-the-api-catalog-ui", From 650f9dfb0ab9197d1c95df809638f2a9b48c53e4 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 2 Apr 2024 14:52:58 +0200 Subject: [PATCH 2/3] fix links/formatting Signed-off-by: Andrew Jandacek --- .../onboard-plain-java-enabler.md | 69 ++++++++++--------- 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/docs/extend/extend-apiml/onboard-plain-java-enabler.md b/docs/extend/extend-apiml/onboard-plain-java-enabler.md index 5a4b2b471b..d456316e51 100644 --- a/docs/extend/extend-apiml/onboard-plain-java-enabler.md +++ b/docs/extend/extend-apiml/onboard-plain-java-enabler.md @@ -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 @@ -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 @@ -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. @@ -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. @@ -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. @@ -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 `/`. @@ -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 `/`. @@ -387,10 +394,9 @@ 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 @@ -398,7 +404,7 @@ where: * **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** @@ -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`** @@ -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** @@ -510,11 +515,9 @@ 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. @@ -522,11 +525,11 @@ where: * **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** @@ -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. @@ -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 @@ -847,8 +852,6 @@ 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: ``` @@ -856,4 +859,6 @@ Add the following code to your configuration file if you use XML configuration: ``` -**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. +::: From ad9ddd4221fa1c8720ed0b9cfba01ce22f4bdf96 Mon Sep 17 00:00:00 2001 From: Andrew Jandacek Date: Tue, 2 Apr 2024 14:59:13 +0200 Subject: [PATCH 3/3] fix links/improve formatting Signed-off-by: Andrew Jandacek --- .../onboard-spring-boot-enabler.md | 46 +++++++++++++------ 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/docs/extend/extend-apiml/onboard-spring-boot-enabler.md b/docs/extend/extend-apiml/onboard-spring-boot-enabler.md index 29bacee46a..7251cd70e1 100644 --- a/docs/extend/extend-apiml/onboard-spring-boot-enabler.md +++ b/docs/extend/extend-apiml/onboard-spring-boot-enabler.md @@ -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 @@ -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. @@ -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. @@ -409,7 +419,8 @@ 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: @@ -417,6 +428,7 @@ logging: ROOT: INFO org.zowe.apiml: DEBUG ``` +::: 3. Provide the suitable parameter corresponding to your runtime environment: @@ -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 @@ -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 @@ -607,8 +624,6 @@ 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: ``` @@ -616,4 +631,7 @@ Add the following code to your configuration file if you use XML configuration: 0 ``` -**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. +:::