Nantes Release Notes (#83)

* nantes release notes

* add release note for 7349

* add discoverability

* fix build

* doc fixes

* add release note

* fixes

* Updated modules and summary.

Co-authored-by: Mitko Pelov <mpelov@axway.com>

content/en/docs/best_practices/_index.md

@@ -106,8 +106,6 @@ When writing code for the [JavaScript flow-node](/docs/developer_guide/flows/flo
 * Set [NODE_ENV=production](https://expressjs.com/en/advanced/best-practice-performance.html) in the environment for security and performance.
 
 ## Managing your service
-
-* The health of your service can be monitored via the health check API `/apibuilderPing.json`
 * The health of your Docker container is monitored via [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck) and uses `./healthcheck.js` to periodically ping the health check API `/apibuilderPing.json`
 * If flow-triggers become unhealthy (e.g. such as an inability to contact Kafka or Solace), your service will shut down as part of best practices for fault-tolerant microservice architecture so that it can [self-heal and auto-restart](https://blog.risingstack.com/designing-microservices-architecture-for-failure/#selfhealing). If you are not using Docker/Kubernetes in production, then you will need to employ a process manager (e.g. [pm2](https://pm2.keymetrics.io/)).
 
@@ -122,3 +120,52 @@ For these reasons, to maintain a healthy service, it is important to update your
 * Use the latest, fully patched version of node that we support (see our [Getting Started Guide](/docs/getting_started) and [{{% variables/apibuilder_prod_name %}} Node.js support policy](/docs/nodejs_support_policy) for version restrictions).
 * Keep your dependencies up to date with their latest patches.
 * Every two weeks, Axway {{% variables/apibuilder_prod_name %}} releases new features, patches, and security fixes. You should keep an eye on our [Release Notes](/docs/release_notes), our list of [Deprecations](/docs/deprecations), and our [Updates](/docs/updates). Keep abreast of the updates to ensure your application will be compatible with any change(s) that may be introduced. Occasionally, you may want to incorporate these security updates and fixes into your application.
+
+## Accessing your service
+* The health of your service can be monitored via the health check API `/apibuilderPing.json`
+* Links to all the API documentation for your service can be found at `/apidocs`. 
+
+### API Discoverability
+With API-first development, {{% variables/apibuilder_prod_name %}} services can implement and expose multiple independent API documents on different URLs. These URLs are not always predictable. Starting with the [Nantes](/docs/release_notes/nantes) release, {{% variables/apibuilder_prod_name %}} services expose an API on the [apidoc prefix](/docs/developer_guide/project/configuration/project_configuration#apidoc) (`/apidoc`) for discovering all API documents and their URLs.
+
+This is an example of the API discoverability response format:
+
+```jsonc
+{
+  // API discoverability response format version
+  "version": "1.0",
+  // Specification types
+  "types": {
+    // Array of individual OpenAPI documents
+    "openapi": [
+      {
+        // document id
+        "id": "dynamic",
+        // document version [optional]
+        "version": "1.0.0",
+        // document name
+        "name": "project",
+        // document description
+        "description": "An {{% variables/apibuilder_prod_name %}} service",
+        // document links.
+        "links": [
+          {
+            // the URL of the document
+            "url": "http://localhost:8080/apidoc/swagger.json",
+            // the mime-type of the document [optional]
+            "mimeType": "application/json",
+            // the version of the specification used by this document (i.e. OpenAPI 2.0) [optional]
+            "specificationVersion": "2.0"
+          },
+          {
+            "url": "http://localhost:8080/apidoc/swagger.yaml",
+            "mimeType": "text/yaml",
+            "specificationVersion": "2.0"
+          }
+        ]
+      }
+    ]
+  }
+}
+
+```

content/en/docs/guide_openapi/managing_apidocs.md

@@ -20,8 +20,7 @@ You can import OpenAPI documents from the _API Doc & Test_ page. Note that [Open
 
 ![OpenAPI import](/Images/openapi_quickstart_import.gif)
 
-Once loaded, you can [update](#updating-openapi-documents) or [delete](#deleting-openapi-documents) the document as required. You can import multiple OpenAPI documents with unique names, but you cannot import another OpenAPI document with the same name.
-
+Once loaded, you can [update](#updating-openapi-documents) or [delete](#deleting-openapi-documents) the document as required.
 ## Binding OpenAPI operations
 
 The [Quick start](/docs/guide_openapi/quick_start) shows how to bind OpenAPI operations flows. When operations are bound, [updating the OpenAPI document](#updating-openapi-documents) subsequently can affect bound operations.

content/en/docs/guide_openapi/quick_start.md

@@ -49,17 +49,12 @@ Now that your **GET /books/{isbn}** is implemented, you can invoke your API.
 1. In the **isbn** parameter field, input `1234`
 1. Click the **Execute** button (you may need to scroll down)
 
-## Accessing the API specification
+## Accessing the API specifications
 
-The OpenAPI specification you imported is served by the {{% variables/apibuilder_prod_name %}} application. From the UI, you can click on the **Summary** page, and then click on **Download OpenAPI specification**.
+The OpenAPI specifications you import are served by the {{% variables/apibuilder_prod_name %}} application. From the UI, you can click on the **API Doc & Test** page, and see all specifications, and their URLs.
 
-The OpenAPI specification is bound to the following paths and is exposed by the service for download:
+The specifications are bound under the `/apidoc` path, for example, the OpenAPI specification for the Bookstore example can be downloaded from `http://localhost:8080/apidoc/openapi/bookstore.yaml`.
 
-* `/apidoc/swagger.json` (for model API and custom API)
-* `/apidoc/swagger.yaml` (for model API and custom API)
-* `/apidoc/openapi.json`
-* `/apidoc/openapi.yaml`
+Some parts of the API specification can be tweaked from the [apidocs.overrides configuration](/docs/developer_guide/project/configuration/project_configuration#apidoc). The "/apidoc" prefix is configured by changing the [`apidoc.prefix`](/docs/developer_guide/project/configuration/project_configuration#apidoc) in the configuration.
 
-Administrators will see only one path in the log. For OpenAPI 2.0, it is `/apidoc/swagger.json`, otherwise, it is `/apidoc/openapi.json`. Some parts of the API specification can be tweaked from the [apidocs.overrides configuration](/docs/developer_guide/project/configuration/project_configuration#apidoc). The "/apidoc" prefix is configured by changing the [`apidoc.prefix`](/docs/developer_guide/project/configuration/project_configuration#apidoc) in the configuration.
-
-For example, the OpenAPI specification can be downloaded from: `http://localhost:8080/apidoc/openapi.yaml`
+Links to all of your application's API specifications can be discovered outside development by accessing the `/apidoc` path directly. For more information see [API discoverability](/docs/best_practices/#api-discoverability).

content/en/docs/guide_openapi/upgrading.md

@@ -105,11 +105,11 @@ For example, if your endpoint has a parameter "IPAddress" that is a string with
 1. Currently unsupported.
 1. Can be used for documentation purposes, but the format is not validated.
 
-### Generated /apidocs/swagger.json
+### Dynamic /apidocs/swagger.json
 
-{{% variables/apibuilder_prod_name %}} has a generated OpenAPI 2.0 specification that can be accessed from `http://localhost:8080/apidocs/swagger.json`.  Previously, this generated spec would contain a mash-up of any [custom API](/docs/developer_guide/apis), [model API](/docs/developer_guide/console/models), and your [Swagger endpoint specifications](https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/flows/manage_endpoints/index.html). Now, the generated `/apidocs/swagger.json` will only contain the custom API, and model API. This "dynamic" API specification will be updated as API or models are added or changed.
+{{% variables/apibuilder_prod_name %}} has a generated OpenAPI 2.0 specification that can be accessed from `http://localhost:8080/apidocs/swagger.json`. This dynamic specification contains a mash-up of any [custom API](/docs/developer_guide/apis), [model API](/docs/developer_guide/console/models), and your [Swagger endpoint specifications](https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/flows/manage_endpoints/index.html), and is updated as API or models are added or changed. It does _not_ contain any API-first specifications after upgrading from endpoints.
 
-However, the API-first specification(s) will be hosted on their own separate [`apidocs` URL](/docs/guide_openapi/quick_start/#accessing-the-api-specification). This means that external applications that might rely on `/apidocs/swagger.json` will have to have some knowledge about these API-first specification URLs, and where to access them.
+The API-first specification(s) will be hosted on their own separate [`apidocs` URL](/docs/guide_openapi/quick_start/#accessing-the-api-specifications). This means that external applications that might rely on `/apidocs/swagger.json` will have to have some knowledge about these API-first specification URLs, and where to access them.
 
 ### Default to application/json
 

content/en/docs/release_notes/nantes.md

@@ -0,0 +1,50 @@
+---
+title: Nantes release notes
+linkTitle: Nantes
+description: 20 May 2022
+date: 2022-05-20
+Hide_readingtime: true
+---
+## Summary
+In this release we added an API for external discoverability of all the API documents that the {{% variables/apibuilder_prod_name %}} service exposes.
+
+{{% releasenotes/upgrade %}}
+
+<!-- ## Breaking changes -->
+
+## Features
+* #7348: Added an API for external discoverability of all the API documents that the {{% variables/apibuilder_prod_name %}} service exposes. This is accessible on the `apidoc.prefix` (default `/apidoc`). For more information see [API discoverability](/docs/best_practices/#api-discoverability).
+
+## Fixes
+* #7287: HTTP request/response logs and flow logs for [@axway/api-builder-plugin-ft-oas](https://www.npmjs.com/package/@axway/api-builder-plugin-ft-oas) no longer have a different request-id for the same request.
+* #7394: [@axway/api-builder-plugin-ft-oas](https://www.npmjs.com/package/@axway/api-builder-plugin-ft-oas) now validates the encoded JSON body against the response schema instead of validating a pre-encoded JavaScript object body which may have different type parameters or extra keys, and could incorrectly fail validation.
+* #7403: Fix issue with npm causing failure to start project after installing using npm version 6 or lower, or using the `--legacy-peer-deps` flag.
+* #7413: Fix issue with [@axway/api-builder-plugin-fn-xslt](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-xslt) where XSLT error messages became less detailed.
+
+{{% releasenotes/deprecations %}}
+
+## Updated modules
+* [@axway/amplify-api-builder-cli@3.3.3](https://www.npmjs.com/package/@axway/amplify-api-builder-cli/v/3.3.3)
+* [@axway/api-builder@6.3.3](https://www.npmjs.com/package/@axway/api-builder/v/6.3.3)
+* [@axway/api-builder-admin@1.63.4](https://www.npmjs.com/package/@axway/api-builder-admin/v/1.63.4)
+* [@axway/api-builder-oas-flow-node@2.6.2](https://www.npmjs.com/package/@axway/api-builder-oas-flow-node/v/2.6.2)
+* [@axway/api-builder-runtime@4.91.1](https://www.npmjs.com/package/@axway/api-builder-runtime/v/4.91.1)
+* [@axway/api-builder-sdk@1.2.1](https://www.npmjs.com/package/@axway/api-builder-sdk/v/1.2.1)
+* [@axway/api-builder-test-utils@1.5.7](https://www.npmjs.com/package/@axway/api-builder-test-utils/v/1.5.7)
+* [@axway/api-builder-openapi-upgrade@1.0.5](https://www.npmjs.com/package/@axway/api-builder-openapi-upgrade/v/1.0.5)
+
+## Updated plugins
+* [@axway/api-builder-plugin-fn-base64@4.1.1](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-base64/v/4.1.1)
+* [@axway/api-builder-plugin-fn-javascript@3.1.1](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-javascript/v/3.1.1)
+* [@axway/api-builder-plugin-fn-json@4.1.1](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-json/v/4.1.1)
+* [@axway/api-builder-plugin-fn-restclient@2.2.2](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-restclient/v/2.2.2)
+* [@axway/api-builder-plugin-fn-swagger@3.2.2](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-swagger/v/3.2.2)
+* [@axway/api-builder-plugin-fn-mustache@1.1.1](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-mustache/v/1.1.1)
+* [@axway/api-builder-plugin-fn-xslt@3.3.0](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-xslt/v/3.3.0)
+* [@axway/api-builder-plugin-fn-logger@1.1.1](https://www.npmjs.com/package/@axway/api-builder-plugin-fn-logger/v/1.1.1)
+* [@axway/api-builder-plugin-ft-oas@1.5.0](https://www.npmjs.com/package/@axway/api-builder-plugin-ft-oas/v/1.5.0)
+
+## Known issues
+For a list of up-to-date known issues see [{{% variables/apibuilder_prod_name %}} known issues](/docs/known_issues/).
+
+{{% releasenotes/previous %}}