madurai release notes (#78)

* madarai release notes

Co-authored-by: Jamie Peabody <jpeabody@axway.com>
Co-authored-by: dvijayakumar <dvijayakumar@axway.com>
Co-authored-by: Alasdair Hurst <ahurst@axway.com>
Co-authored-by: Mitko Pelov <mpelov@axway.com>

README.md

@@ -63,3 +63,42 @@ Named plugins shall be bold, but only the name, not the type.
 ### Pages
 
 Pages, such as _API Doc & Test_ shall be written in italic, and exactly as they appear in the UI.
+
+## Recording GIFs
+
+We record animated GIFs for better visualisation of process in the docs. We should be consistent when recording though, so everyone should follow the same steps to ensure that the docs look uniform and the animations are a reasonable file size.
+
+Tools:
+* Chrome
+* [Window resizer chrome extension](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh/related?hl=en) 
+* [LICEcap](https://www.cockos.com/licecap/)
+
+GIF properties:
+* 1240x720
+* 5fps
+* Infinite repeat count
+* The cursor is displayed
+* The entire viewport is recorded, but not the browser itself
+* Browser is at 100% zoom
+
+### Configuring utilities
+
+Ensure LICEcap is set to the correct fps and image size. This should be persisted, so only need to set it once.
+![Setup LICEcap](/static_readme/licecap_setup.gif)
+
+Install and configure Window resizer. I recommend setting a preset for API Builder recording.
+
+Ensure your resize target is viewport, and your width and height are 1240x720.
+
+The most annoying part of this is lining up the chrome window and LICEcap window. Click "use current" when configuring the Window resizer preset. This will allow you to keep the chrome window aligned with your LICEcap window in order to avoid having to reposition it to link up.
+
+![Setup Window resizer](/static_readme/window_resizer_settings.png)
+
+![capture screen](/static_readme/capture_screen.png)
+
+You may also need to open the console in your browser to stop the bottom edges being curved. You may also want to use the built-in magnifier (zoom on Mac) to ensure the recording viewport lines up correctly.
+
+### Recording
+When clicking record in LICEcap, ensure the following settings are configured.
+![Setup Window Resizer](/static_readme/licecap_settings.png)
+

content/en/docs/developer_guide/connectors/mssql_connector.md

@@ -5,13 +5,13 @@ weight: 30
 date: 2021-10-01
 ---
 
-The Microsoft SQL Server data connector is a plugin for {{% variables/apibuilder_prod_name %}} that can connect to your MSSQL instance and interrogate your schema that will automatically provision Models into your project, and optionally, automatically generate a rich CRUD API to the underlying tables. The Models can be used programmatically or can be used within the flow editor to interact with your database.
+The Microsoft SQL Server data connector is a plugin for {{% variables/apibuilder_prod_name %}} that can connect to your MSSQL instance and interrogate your schema that will automatically provision Models into your project, and optionally, automatically generate a rich CRUD API to the underlying tables. The Models can be used programmatically, or can be used within the flow editor to interact with your database.
 
 ## Minimum requirements
 
 The following are the supported versions and features and the approximate memory and disk space requirements.
 
-### Supported Versions
+### Supported versions
 
 * SQL Server 2008 or later
 
@@ -31,21 +31,19 @@ The following are the supported versions and features and the approximate memory
 
 ## Installation
 
-To install the MSSQL connector, execute the following command:
-
 ```bash
 npm install --no-optional @axway/api-builder-plugin-dc-mssql
 ```
 
-A configuration file is generated for you and placed into the **`/conf`** directory of your {{% variables/apibuilder_prod_name %}} project. By default, we use a host of `localhost`, and expect user and password to come from the OS host environment.
+A configuration file is generated for you and placed into the `./conf` directory of your {{% variables/apibuilder_prod_name %}} project. By default, we use a host of `localhost`, and expect user and password to come from the OS host environment.
 
 ## Configuration
 
 Once the plugin is installed, the configuration file is located in `<project>/conf/mssql.default.js`.
 
 | Option name | Type | Description |
-| --- | --- | --- |
-| connector | string | Must be: `@axway/api-builder-plugin-dc-mssql` |
+| ----------- | ---- | ----------- |
+| connector   | string | Must be: `@axway/api-builder-plugin-dc-mssql` |
 | user | string | The user with which to connect to the database. |
 | password | string | The user's password with which to connect to the database. |
 | host | string | The database host. |
@@ -56,35 +54,66 @@ Once the plugin is installed, the configuration file is located in `<project>/co
 | generateModelsFromSchema | boolean | If enabled, {{% variables/apibuilder_prod_name %}} will automatically interrogate the database and auto-generate Models from SQL tables. |
 | modelAutogen | boolean | If enabled, {{% variables/apibuilder_prod_name %}} will automatically generate a full and rich CRUD API from the generated Models. |
 | options | object | MSSQL Connection options |
-| options.encrypt | boolean | Encrypt the database connection. Required when connecting to Azure. Defaults to true. |
-| options.trustServerCertificate | boolean | When options.encrypt is true, this will explicitly trust the SQL Server certificate even if it is untrusted (e.g. self-signed, invalid SNI, etc). Do not set to true in production. |
+| options.encrypt | boolean | Encrypt the database connection. Required when connecting to Azure. |
 
 ## Usage
 
-After you configure the connector, you can start up your {{% variables/apibuilder_prod_name %}} project and visit the console (normally found under`http://localhost:8080/console`). Your database tables will be listed on the **Models** tab of the console. Now, you can click on the **Gear** icon to the right of the table names and generate flow-based APIs.
+After you configure the connector, you can start up your {{% variables/apibuilder_prod_name %}} project and visit the console (normally found under http://localhost:8080/console). Your connector will also be listed as a **Connector** when creating a [new model](https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/models/create/index.html#create-a-new-model) in the console.
+
+Your database tables will be listed under the [Models](http://localhost:8080/console/project/models) section of the console. You can now click on the gear icon to the right of the table names and generate flow based APIs.
 
 You can also reference the connector in a custom model.
 
 ```javascript
 const Account = APIBuilder.Model.extend('Account', {
   fields: {
-    Name: { type: String, required: true }
+    Name: {
+      type: String,
+      required: true
+    }
   },
   connector: 'mssql'
 });
 ```
 
-If you want to map a specific model to a specific table, use metadata. For example, to map the `account` model to the `accounts` table set it as:
+If you want to map a specific model to a specific table, use metadata for `schema` and `table` name.  For example, to map the `account` model to the table named the table "\[dbo\].\[accounts\]":
+
+```javascript
+const Account = APIBuilder.Model.extend('account', {
+  fields: {
+    Name: {
+      type: String,
+      required: false,
+      validator: /[a-zA-Z]{3,}/
+    }
+  },
+  connector: 'mssql',
+  metadata: {
+    schema: 'dbo',
+    table: 'accounts'
+  }
+});
+```
+
+If your table has a primary key, then you can use additional metadata:
 
 ```javascript
 const Account = APIBuilder.Model.extend('account', {
   fields: {
-    Name: { type: String, required: false, validator: /[a-zA-Z]{3,}/ }
+    Name: {
+      type: String,
+      required: false,
+      validator: /[a-zA-Z]{3,}/
+    }
   },
   connector: 'mssql',
   metadata: {
-    'mssql': {
-      table: 'accounts'
+    schema: 'dbo',
+    table: 'accounts',
+    primarykey: 'Name',
+    primaryKeyDetails: {
+      autogenerated: false,
+      type: 'varchar'
     }
   }
 });

content/en/docs/developer_guide/console/_index.md

@@ -53,11 +53,13 @@ The **Summary** tab lists basic information about your application like app name
 
 ### API Doc & Test tab
 
-On startup, API endpoints are automatically generated for all models as per their default configuration. An API provides a way for a client to access your application, such as `GET <SERVER_ADDRESS>/api/users/query`, execute custom logic, internally access the application's models and APIs, and return data to the client application.
+An API document or specification is a file which defines the methods which are available on a service, how they are accessed, and what responses are expected. The **API Doc & Test** tab lists all specifications that your service implements.
 
-The **API Doc & Test** tab in the Admin Console contains generated docs of your application APIs, including how to call the API, multiple examples, and the ability to test the APIs. The generated docs use the information in the `description` fields of your JavaScript definition files to fill in some of the information. API definitions can also be imported by selecting the **\+ API** button. You can import an API from a Swagger definition by either selecting a file from your local file system or entering a URL. For additional information, refer to [Manage Endpoints](/docs/developer_guide/flows/manage_endpoints/).
+Documents may be dynamically generated from components of your service, such as the _Dynamic_ OpenAPI 2.0 specification created by default on all services. External documents may also be imported and implemented using [API-first methodologies](/docs/guide_openapi/quick_start).
 
-![localhost_8080_console_project_summary_%281%29](/Images/localhost_8080_console_project_summary_(1).png)
+_Dynamic_ specifications take their name and description from your services `package.json`.
+
+![API Doc & Test tab](/Images/console_tab_api_doc_and_test.png)
 
 ### Flows tab
 

content/en/docs/getting_started/_index.md

@@ -161,3 +161,5 @@ However, we recommend that you do not change the environmentalized port configur
 ## Further reading
 
 Once you are familiar with startup and the UI, be sure to read the [Best Practices](/docs/best_practices/) guide as it will help guide your next phase of development.
+
+For additional {{% variables/apibuilder_prod_name %}} demos, examples and use-cases, check out posts on the [Axway Blog](https://blog.axway.com/tag/api-builder).

content/en/docs/release_notes/madurai.md

@@ -0,0 +1,42 @@
+---
+title: Madurai release notes
+linkTitle: Madurai
+description: 6 May 2022
+date: 2022-05-06
+Hide_readingtime: true
+---
+## Summary
+
+In this release we enhanced the **API Doc & Test** page to specifically list all available API specifications that the service implements, as well as where these documents can be accessed from. As usual, the specifications can be viewed, and APIs they contain can be tested and it is now more easy to download. The _Dynamic_ OpenAPI specification created for every service is no longer hidden and is now visible on the **API Doc & Test** page. Additionally, we added support for non-default table schemas in the MSSQL plugin.
+
+{{% releasenotes/upgrade %}}
+
+<!-- ## Breaking changes -->
+
+## Features
+
+* #7358: The **API Doc & Test** page has been updated to show all top level API specifications documented by your service, and where they can be downloaded.
+* #7357: A new item for the _Dynamic_ OpenAPI specification (`/apidoc/swagger.json`) has been added to **API Doc & Test** for all services. Individual API groups (for example for auto-generated model APIs or programmatic APIs) have been removed from this list and are now visible and testable as part of the _Dynamic_ API specification. 
+* #7356: Added the ability to individually download any of the existing service API specifications directly from the **API Doc & Test** page, as well as from the respective specification pages.
+* #7371: The [MSSQL connector](/docs/developer_guide/connectors/mssql_connector) plugin now supports tables created in schema other than the database user's default schema (usually `dbo`).
+* #7374: When creating new models, API methods are not enabled by default.
+
+## Fixes
+
+* #7117: Previously unhandled conflicts between OpenAPI paths and other API paths in your service are now detected.
+
+{{% releasenotes/deprecations %}}
+
+<!-- Regenerate modules/plugins with api-builder-tools script -->
+## Updated modules
+* [@axway/api-builder-admin@1.63.0](https://www.npmjs.com/package/@axway/api-builder-admin/v/1.63.0)
+* [@axway/api-builder-runtime@4.89.0](https://www.npmjs.com/package/@axway/api-builder-runtime/v/4.89.0)
+
+## Updated plugins
+* [@axway/api-builder-plugin-dc-mssql@3.3.0](https://www.npmjs.com/package/@axway/api-builder-plugin-dc-mssql/v/3.3.0)
+
+## Known issues
+
+For a list of up-to-date known issues see [{{% variables/apibuilder_prod_name %}} known issues](/docs/known_issues/).
+
+{{% releasenotes/previous %}}