Merge pull request #32 from cap-js/doc

Documentation

README.md

@@ -1,4 +1,4 @@
-[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/cds-plugin-for-ord)](https://api.reuse.software/info/github.com/cap-js/cds-plugin-for-ord)
+[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/ord)](https://api.reuse.software/info/github.com/cap-js/cds-plugin-for-ord)
 
 # CDS Plugin for ORD
 
@@ -45,6 +45,10 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 
 <img width="1300" alt="Sample Application Demo" style="border-radius:0.5rem;" src="./asset/etc/ordEndpoint.gif">
 
+### Customizing ORD Document
+
+You can find more information, such as how to customize the ORD Document, in this [document](ord.md).
+
 
 ## Support, Feedback, Contributing
 

ord.md

@@ -0,0 +1,73 @@
+# cap-js ORD (Open Resource Discovery) Plugin
+
+The cap-js ORD plugin has a default behavior where all the values of the ORD document are generated automatically by the plugin without the user giving them explicitly.
+
+If this default behavior is to be overwritten , then there are two ways in which it could be done.
+
+For all the application level felids it is done using `present configuration` ( in `./cdsrc.json` under `ord` section).
+
+Example:
+
+```js
+ "ord": {
+        "namespace": "sap.sample",
+        "description": "this is my custom description",
+        "policyLevel": "sap:core:v1"
+    }
+
+```
+
+For all the service level felids it is done using annotations ( in the `.cds` files as `@ORD.Extensions`).
+
+Example:
+
+```js
+annotate ProcessorService with @ORD.Extensions : {
+    title           : 'This is Processor Service title',
+    shortDescription: 'short description for Processor Service',
+    visibility : 'public',
+    extensible : {
+      supported : 'no'
+    }
+};
+
+```
+
+Also note that annotations like `@Core.Description` and `@description` are also read.
+The overwriting happens in the following priority : ord.extensions annotations > cap annotations > defaults.
+
+The below is the table for all the supported ORD Fields containing defaults and how to overwrite the same.
+
+Note: `namespace` is usually taken from `.cdsrc.json` if not we take the `package.json` name. 
+
+
+| ORD Field  | Type | Defaults | Preset/Annotation | Usage Example | Description |
+|----------|----------|----------|----------|----------|----------|
+| openResourceDiscovery    | string  |-   | -  | -   | 1.9 (generated by plugin)  |
+| policyLevel    | string   | ```"none"```   | Preset   |```"policyLevel": "sap:core:v1"``` | The policy level (aka. compliance level) that this ORD Document or part of it needs to be compliant with.   |
+| description    | string   | ```"description": "this is an application description"```   | Preset   | ```"description": "this is a custom description"```  | The description of the ORD Document itself.   |
+| Products Array    | Array of JSON objects  | ----------   | Preset ( as a full product list which will be overwritten)  | -----------------   | A product in ORD is understood as a commercial product or service. |
+| ordId    | string   | ```"ordId": "customer:product:<namespace>:"```   |    | ```"ordId": "customer:product:sampleORDdemo:```   | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.  |
+| title    | string   | ```"title": "ORD App Title for <namespace>"```   |    |  ```"title": "ORD App Title for sampleORDdemo"```  | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks.   |
+| shortDescription    | string   | ```"shortDescription": " shortDescription for products"```   |   | ```"shortDescription": " shortDescription for products"```   | Plain text short description.MUST NOT exceed 255 chars. MUST NOT contain line breaks.   |
+| vendor    | string   | ```"vendor": "customer:vendor:SAPCustomer:"```   |    | ```"vendor": "sap:vendor:SAPCustomer:"```   | Vendor / organization that is responsible for the Product.   |
+| groups Array    | Array of JSON objects   |  -  |   - |   - | Group (instance) that resources can be assigned to.hey express a "part of" relationship to the chosen group concept.   |
+| groupId   | string   | ```"groupId": "sap.cds:service:customer.<namespace>:sap.capire.incidents.ProcessorService"```   |  -  | -   | The Group ID consists of two Concept IDs separated by a `:`.   |
+| groupTypeId   | string   | ```"groupTypeId": "sap.cds:service"```   | -   | -   | Group Type ID.   |
+| title   | string   | ```"title": "This is Processor Service title"```| Annotation   | ```annotate AdminService with @ORD.Extensions : {title : 'This is Admin Service title'};```   | Human readable title of the group assignment (for UI).   |
+| packages   | Array of JSON objects   | -   | Present (as a full product list which will be overwritten)   | -   | A Package organizes a set of related resources together, by publishing and catalog presentation concerns.   |
+| ordId   | string   | ```"ordId":"customer.<namespace>:package:<namespace>:v1"```   |    |    | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.   |
+| title   | string   | ```"title": "sample title for <namespace>"```   | -   | -   | Human-readable title.MUST NOT exceed 255 chars. MUST NOT contain line breaks.   |
+| shortDescription   | string   | ```"shortDescription": "Here is the shortDescription for packages"```   | -   | -   | Plain text short description.MUST NOT exceed 255 chars. MUST NOT contain line breaks.   |
+| description   | string   | ```"description": "Here is the description for packages",```   | -   | -   | Full description, notated in CommonMark (Markdown).   |
+| version   | string   | ```"version": "1.0.0"```   | -   | -   | The complete SemVer version string.   |
+| partOfProducts   | Array of strings   | ```"partOfProducts": ["customer:product:<namespace>:"]```   | -   | -   | List of products this resource is a part of.   |
+| vendor   | string   | ```"vendor": "customer:vendor:SAP:"```   | -   | -   | Vendor / organization that is the creator (or responsible party) of the resources that are part of the Package.   |
+| consumptionBundles   | string   | Array of JSON objects    | Present (as a full consumptionBundles list which will be overwritten)   | -   | A Consumption Bundle groups APIs and Events together that can be consumed with the credentials and auth mechanism. Ideally it also includes instructions and details how to request access and credentials for resources.   |
+| ordId   | string   | ```"ordId": "customer.<namespace>:consumptionBundle:unknown:v1"```   | -   | -   | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. |
+| version   | string   | ```"version": "1.0.0"```    | -   | -   | The complete SemVer version string.   |
+| title   | string   | ```"title": "Unprotected resources"```   | -   | -   | Human-readable title.MUST NOT exceed 255 chars. MUST NOT contain line breaks.    |
+| shortDescription   | string   | ```"shortDescription": "If we have another protected API then it will be another object"```   | -   | -   | Plain text short description.MUST NOT exceed 255 chars.MUST NOT contain line breaks.   |
+| description   | string   | ```"description": "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication"```   | -   | -   | Full description, notated in CommonMark (Markdown)   |
+| apiResources   | Array of JSON Objects   |    | Cannot be modified by the user ( The plugin generates based on the number of services defined in the CAP Application)  |    | The API Resource provides a high-level description of an exposed API.    |
+| eventResources   | Array of JSON Objects   | -   | Cannot be modified by the user ( The plugin generates based on the number of services that have events defined in the CAP Application)   |    | The event resource provides a high-level description of a collection of related Events. More detailed information, such as the event resource definitions.   |