feat: add application API documentation (#219)

* add spec * add application api genereated docs * add config * update GDS * fix authorization * wip * wip * wip * wip
tapioone · Feb 19, 2024 · 62c9bf5 · 62c9bf5
1 parent a0afd39
commit 62c9bf5
Show file tree

Hide file tree

Showing 18 changed files with 969 additions and 18 deletions.
diff --git a/docs/api/application-api/application-api.info.mdx b/docs/api/application-api/application-api.info.mdx
@@ -0,0 +1,25 @@
+---
+id: application-api
+title: "Application API"
+description: "tapio's Application API enables third party applications to interact with tapio on behalf of their users."
+sidebar_label: Introduction
+sidebar_position: 0
+hide_title: true
+custom_edit_url: null
+---
+
+import ApiLogo from "@theme/ApiLogo";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import Export from "@theme/ApiDemoPanel/Export";
+
+<span className={"theme-doc-version-badge badge badge--secondary"}>Version: 1</span>
+
+# Application API
+
+
+
+tapio's Application API enables third party applications to interact with tapio on behalf of their users.
+
+<div style={{"marginBottom":"2rem"}}><h2 id={"authentication"} style={{"marginBottom":"1rem"}}>Authentication</h2><SchemaTabs className={"openapi-tabs__security-schemes"}><TabItem label={"OAuth 2.0: oauth2"} value={"oauth2"}><div><table><tbody><tr><th>Security Scheme Type:</th><td>oauth2</td></tr><tr><th>OAuth Flow (implicit):</th><td><p>Authorization URL: https://login.mytapio.one/32896ed7-d559-401b-85cf-167143d61be0/B2C_1A_Tapio_Signin/oauth2/v2.0/authorize</p><span>Scopes:</span><ul><li>openid: openid</li><li>https://tapiousers.onmicrosoft.com/7ee7f1b0-d030-4d20-9691-9752bdb44315/Consent.ReadWrite: read and write consent</li></ul></td></tr></tbody></table></div></TabItem></SchemaTabs></div><div style={{"display":"flex","flexDirection":"column","marginBottom":"var(--ifm-paragraph-margin-bottom)"}}><h3 style={{"marginBottom":"0.25rem"}}>Contact</h3><span>tapio GmbH: <a href={"mailto:[email protected]"}>[email protected]</a></span><span>URL: <a href={"https://tapio.one"}>https://tapio.one</a></span></div><div style={{"marginBottom":"var(--ifm-paragraph-margin-bottom)"}}><h3 style={{"marginBottom":"0.25rem"}}>Terms of Service</h3><a href={"https://tapio.one/en/tapio-terms-of-use"}>https://tapio.one/en/tapio-terms-of-use</a></div>
+
diff --git a/docs/api/application-api/consent-subject.tag.mdx b/docs/api/application-api/consent-subject.tag.mdx
@@ -0,0 +1,16 @@
+---
+id: consent-subject
+title: "ConsentSubject"
+description: "ConsentSubject"
+custom_edit_url: null
+---
+
+
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+```
+
diff --git a/docs/api/application-api/evaluate-consent.api.mdx b/docs/api/application-api/evaluate-consent.api.mdx
diff --git a/docs/api/application-api/get-consent-subjects.api.mdx b/docs/api/application-api/get-consent-subjects.api.mdx
diff --git a/docs/api/application-api/grant-consent.api.mdx b/docs/api/application-api/grant-consent.api.mdx
diff --git a/docs/api/application-api/me.tag.mdx b/docs/api/application-api/me.tag.mdx
@@ -0,0 +1,16 @@
+---
+id: me
+title: "Me"
+description: "Me"
+custom_edit_url: null
+---
+
+
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+<DocCardList items={useCurrentSidebarCategory().items}/>
+```
+
diff --git a/docs/api/application-api/sidebar.js b/docs/api/application-api/sidebar.js
diff --git a/docs/api/gds/get-application-settings.api.mdx b/docs/api/gds/get-application-settings.api.mdx
diff --git a/docs/api/gds/get-application-token-profile.api.mdx b/docs/api/gds/get-application-token-profile.api.mdx
diff --git a/docs/api/gds/get-subscription-overview.api.mdx b/docs/api/gds/get-subscription-overview.api.mdx
diff --git a/docs/api/gds/get-user-profile.api.mdx b/docs/api/gds/get-user-profile.api.mdx
diff --git a/docs/api/gds/onboard-cloud-connector.api.mdx b/docs/api/gds/onboard-cloud-connector.api.mdx
@@ -46,7 +46,7 @@ Onboarding information of the cloud connector
 
 Successful
 
-</div><div><MimeTabs schemaType={"response"}><TabItem label={"text/plain"} value={"text/plain"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2023-03-21T16:47:39.304Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2023-03-21T16:47:39.304Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem><TabItem label={"text/json"} value={"text/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2023-03-21T16:47:39.304Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"400"} value={"400"}><div>
+</div><div><MimeTabs schemaType={"response"}><TabItem label={"text/plain"} value={"text/plain"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2024-02-19T09:55:09.200Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem><TabItem label={"application/json"} value={"application/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2024-02-19T09:55:09.200Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem><TabItem label={"text/json"} value={"text/json"}><SchemaTabs><TabItem label={"Schema"} value={"Schema"}><details style={{}} data-collapsed={false} open={true}><summary style={{"textAlign":"left"}}><strong>Schema</strong></summary><div style={{"textAlign":"left","marginLeft":"1rem"}}></div><ul style={{"marginLeft":"1rem"}}><SchemaItem collapsible={false} name={"activationCode"} required={false} schemaName={"string"} qualifierMessage={undefined} schema={{"type":"string","description":"The 12-digit activation code for the machine onboarding","nullable":true}}></SchemaItem><SchemaItem collapsible={false} name={"expiry"} required={false} schemaName={"date-time"} qualifierMessage={undefined} schema={{"type":"string","description":"Expiry date","format":"date-time"}}></SchemaItem></ul></details></TabItem><TabItem label={"Example (from schema)"} value={"Example (from schema)"}><ResponseSamples responseExample={"{\n  \"activationCode\": \"string\",\n  \"expiry\": \"2024-02-19T09:55:09.200Z\"\n}"} language={"json"}></ResponseSamples></TabItem></SchemaTabs></TabItem></MimeTabs></div></TabItem><TabItem label={"400"} value={"400"}><div>
 
 Bad request
 

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,5 +1,6 @@
 # API Reference
 
 - [Global Discovery Service API](./gds)
+- [Application API](./application-api)
 - *Core API (TBD)*
 - *Management API (TBD)*
diff --git a/docs/general/available-apis.md b/docs/general/available-apis.md
@@ -24,6 +24,7 @@ We're using some services provided by Microsoft, to authenticate applications an
 | Core API                     | Retrieve machine states and send commands to a machine                        | `https://core.tapio.one/`          | [Access Machine States](../machine-data/state-api), [-read Historical Data](../machine-data/historical-data), [Send Commands to a Machine](../machine-data/Commanding) | Client Credential Flow | `https://tapiousers.onmicrosoft.com/CoreApi`                |
 | Global Discovery Service API | Retrieve the profile of a user, including assigned subscriptions and machines | `https://globaldisco.tapio.one/`   | [Retrieve Profile of a User](./user-profile), [API Reference](../api/gds)                                    | Client Credential Flow | `https://tapiousers.onmicrosoft.com/GlobalDiscoveryService` |
 | Management API               | Create and manage your tapio machines                                         | `https://api.tapio.one/management` | [Manage your Machines](../manufacturer)                                                                                                                                | Client Credential Flow | `https://tapiousers.onmicrosoft.com/ManagementApiGateway`   |
+| Application API | Enables third party applications to interact with tapio on behalf of their users | https://api.tapio.one/application | [API Reference](../api/application-api) | Authorization Code Flow | `https://tapiousers.onmicrosoft.com/7ee7f1b0-d030-4d20-9691-9752bdb44315` |
 
 Policies
 ______

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -142,7 +142,7 @@ module.exports = {
     [
       'docusaurus-plugin-openapi-docs',
       {
-        id: "apiDocsGds",
+        id: "apiDocs",
         docsPluginId: "classic",
         config: {
           gds: {
@@ -153,6 +153,14 @@ module.exports = {
               categoryLinkSource: "tag"
             }
           },
+          applicationApi: {
+            specPath: "src/api/ApplicationApi.json",
+            outputDir: "docs/api/application-api",
+            sidebarOptions: {
+              groupPathsBy: "tag",
+              categoryLinkSource: "tag"
+            }
+          },
         },
       }
     ],

diff --git a/sidebars.js b/sidebars.js
@@ -97,6 +97,16 @@ module.exports = {
           },
           items: require("./docs/api/gds/sidebar.js"),
         },
+        {
+          type: "category",
+          label: "Application API",
+          link: {
+            type: "generated-index",
+            title: "Application API",
+            slug: "/api/application-api",
+          },
+          items: require("./docs/api/application-api/sidebar.js"),
+        },
       ],
     },
     {