docs: better openapi spec (#4397)

Co-authored-by: Matthew Elwell <[email protected]>

.github/workflows/docs-pull-request.yml

@@ -29,8 +29,6 @@ jobs:
 
       - name: npm install
         run: npm ci --include=dev --ignore-scripts
+
       - name: Run docusaurus build to check for broken links etc
-        run: |
-          npx prettier --version
-          npx prettier --check docs
-          npm run build
+        run: npm run build

.prettierignore

@@ -4,4 +4,10 @@
 *.handlebars
 *.css
 .bablerc
-**/CHANGELOG.md
+**/CHANGELOG.md
+
+# Auto generated by open API generator
+docs/docs/edge-api/*.mdx
+docs/docs/edge-api/sidebar.ts
+
+.prettierignore

docs/README.md

@@ -38,6 +38,18 @@ If you want to apply any fixes discovered, you can run the following command:
 npx prettier <YOUR_DOC> --write
 ```
 
+## OpenAPI generator
+
+We are using the https://github.com/PaloAltoNetworks/docusaurus-openapi-docs plugin to generate the OpenAPI docs. If
+`static/api-static/edge-api.yaml` changes you will need to rebuild the static files with:
+
+```bash
+npm run docusaurus clean-api-docs all
+npm run docusaurus gen-api-docs all
+```
+
+and then commit them.
+
 ## Build
 
 ```console

docs/docs/clients/rest.md

@@ -53,6 +53,8 @@ administrative area.
 
 For SaaS customers, the URL to hit for this API is [`https://edge.api.flagsmith.com/`](/advanced-use/edge-api).
 
+Our Edge API specification is detailed [here](/edge-api/overview).
+
 ### Private Admin API Endpoints
 
 You can also do things like create new flags, environments, toggle flags or indeed anything that is possible from the

docs/docs/edge-api/Overview.md

@@ -0,0 +1,19 @@
+---
+id: overview
+title: Edge API Overview
+sidebar_position: 1
+sidebar_label: Overview
+---
+
+## Authentication
+
+The Edge API is designed to be publicly accessible. Calls need to have an environment key supplied with each request.
+This is provided as an HTTP header, with the name `X-Environment-Key` and the value of the Environment Key that you can
+find within the Flagsmith administrative area.
+
+## Core API
+
+Please note that the Edge API is specifically to be used with our [SDKs](/clients). If you want to drive aspects of
+Flagsmith programmatically, you need to use our private [Core API](/clients/rest#private-admin-api-endpoints).
+
+You can find the full spec to our Core API [here](https://api.flagsmith.com/api/v1/docs/).

docs/docs/edge-api/_category_.yaml

@@ -0,0 +1 @@
+className: hidden

docs/docs/edge-api/bulk-insert-identities-overwrite.api.mdx

@@ -0,0 +1,74 @@
+---
+id: bulk-insert-identities-overwrite
+title: "Bulk insert identities (overwrite)"
+description: "Bulk uploading identities and traits. If there is an existing identity, using POST will overwrite the existing identity with the data from the request."
+sidebar_label: "Bulk insert identities (overwrite)"
+hide_title: true
+hide_table_of_contents: true
+api: eJzdVd9P2zAQ/lcsP21SmxbWp77RDaRqEiBg0iRAk5NcGoNje7ZTqKL+77tzQmso2st4Wh+q+Pzd7+/OHQ9i5fn8lp+WK2Anl0t+P+Il+MJJG6TRfM4XrXpkrVVGlFKvmCxBBxkkeCZ0yYITMviMLSsWanDAJMkZPEsfEvhmxFpP58uL6xv2JJViZg3uyckApHiogKBQx6tSBMEqZ5p4cvC7BR+yO32nl4HVAv0xJRsZmKnY0XSaRmjBJQp8xIfDwpQbPu94YXRAMH0Ka5UsBCU9efCUecd9UUMj6CtsLGAtTP4ARUA78Cwaq1DUbUfcOoOOyCFBKdxERTgnNqiBiTb+PVOvtft6/qP+r0fYJFAfHFY2jZqfiwY4ht7D10K1lAs3Gi4qpMPfVBfZScYWwomi9WhiB9Vtk4NLobPj5Do3RoHQ6X1wLWyRb7pVSuQ7CYUlQ/R1Q+FxkvRNrSR6OEgs1Vjumn/Vt/obtWObQojQe9jL/ZbI4a3Rvi/k8fQ4dvPVLJwUBdgAJZVuNp0eAhaiZINjzDShV4DnMLFKyPeJtavza3PnsaZE7ITUTesD0yawHFhjHM0PThwyf0hjNv1yGNiZcbks0chHhHXhVkJLH4eFBr7Eb+xf2U+pB7emSa4U7pZsF9TsMKhzTOLMtLr8iKBO9Vo6oxs0EqtTRcPb3n0DoTYloqyJnbEi1Hia5MiF8b62eEPRg/NxCFqnEFSHYP18MgFckZmwMouJ4cKps8I0E5RM1keH4bwsVGK4h6LFVbeJVpNAv9Oc3t6nkGtKt6fgW+B+J1hJApwK8lSDKOPgaRrqOf85ThTHBKQK0E672m+/03SBSV2ZaH6YkF3sI0616BM6ItJT+RoR+zJ4i8+DxKlxISXpp916//y2NMna/b8el6E7CX2xYpFD3UC4W/6WcNj5miiJV12XCw8/nNpuSYyGXWQHNkE42S9I5MropeHEpbjo+de+nuMbCoDgcZ0fPmm0jnuNfpEl2DTo+2ReqKQIy4cHszEloZ14oscU/+ccP0zsbORslHVcCb1qxYqwvWf6/QF6le6J
+sidebar_class_name: "post api-method"
+info_path: edge-api/edge-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Bulk insert identities (overwrite)"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"post"}
+  path={"/bulk-identities"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Bulk uploading identities and traits. If there is an existing identity, using POST will overwrite the existing identity with the data from the request.
+
+It has a limit of 100 identities per request.
+
+
+<Heading
+  id={"request"}
+  as={"h2"}
+  className={"openapi-tabs__heading"}
+  children={"Request"}
+>
+</Heading>
+
+<ParamsDetails
+  parameters={undefined}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={{"content":{"application/json":{"schema":{"type":"object","example":{},"properties":{"data":{"type":"array","items":{"type":"object","properties":{"traits":{"type":"array","items":{"type":"object","properties":{"trait_key":{"type":"string","example":"Name"},"trait_value":{"oneOf":[{"type":"string","example":"B.A. Baracus"},{"type":"number","example":42},{"type":"boolean","example":true}],"nullable":true}},"title":"Trait"}},"identifier":{"type":"string"}},"title":"IdentitiesRequestData"}}},"title":"BulkIdentitiesData"}}}}}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"type":"string","description":"Number of identities must not be more than 100"}}}},"403":{"description":"Forbidden","content":{"text/plain":{"schema":{"type":"string","description":"Organisation is disabled from serving flags."}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"type":"string","description":"Environment not found"}}}}}}
+>
+
+</StatusCodes>
+
+
+

docs/docs/edge-api/bulk-insert-identities-update.api.mdx

@@ -0,0 +1,74 @@
+---
+id: bulk-insert-identities-update
+title: "Bulk insert identities (update)"
+description: "Bulk uploading identities and traits. If there is an existing identity, using PUT will update the existing identity with the data from the request."
+sidebar_label: "Bulk insert identities (update)"
+hide_title: true
+hide_table_of_contents: true
+api: eJzdVd9P2zAQ/lcsP21SmxbWp77RDaRqEiAG0iRAkxNfGkNie7ZTqKL+77tzQmso2st4Wh+q+Pzd7+/OHQ9i5fn8lp/KFbCTyyW/H3EJvnDKBmU0n/NFWz+y1tZGSKVXTEnQQQUFngktWXBCBZ+xZclCBQ6YIjmDZ+VDAt+MWOvpfHlzzZ5UXaNFKQKQ0iEYEaGKV4gRrHSmiScHv1vwIbvTd3oZWCXQF6tVowIzJTuaTtPoLLhEgY/4cFgYueHzjhdGBwTTp7C2VoWghCcPnrLuuC8qaAR9hY0FrIPJH6AIaAeeRWNrFHXbEbfOoCNySFAKN1ERzokNaqgAjX/P1Gvtvpb/qP/rETYJ1AeHlU2j5ueiAY6h9/C1qFvKhRsNFyVS4W+qi+wkYwvhRNF6NLGD6rbJwaXQ2XFynRtTg9DpfXAtbJFruq1rke8kFJYK0dc1hcdJ0je1VOjhILFUY7lr/lXf6m/Ujm0KITLvYS/3WyKHt0b7vpDH0+PYzVdzcFIUYANIKt1sOj0ELIRkg2PMNKFXgOcwsbVQ7xNrV+fX5s5jTYnYCamb1gemTWA5sMY4mh+cNmT+kMZs+uUwsDPjciXRyEeEdeFWQisfh4WGXeI39k/2U+rBrWmSyxr3SrYLanYY1DkmcWZaLT8iqFO9Vs7oBo3E6pTR8LZ330CojESUbePMiFDhYZIjFcb70uINBQ/OxxloXY2gKgTr55MJ4HbMhFVZzAv3TZUVppmgZLI+OozmZZcSwT0UrcOdFq0mcX6nMb29TyE/KNuegW+B+5VgFQlwKMhTBULGudM003P+c5wojglIBaCVdrVffqfp/lK6NNH8MCC72EecatEndESct8aHRsS2DN7iy6BwaFxIOfqpX+2f39YlWbn/z6MytCWhLZYqkqcbmHbL3zINW15hMemq63Lh4cbV2y2J0bCLtMDqC6f6xYgkGb10mkgUFzz/2tdyfE0BEDyu8cOnjNZwr9EvsASbBn2fzAmWE1H58E42RhLYiSd6Q/F/zvHDxKZGrkZZx2uhV61YEbZ3TL8/nsHpCQ==
+sidebar_class_name: "put api-method"
+info_path: edge-api/edge-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Bulk insert identities (update)"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"put"}
+  path={"/bulk-identities"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Bulk uploading identities and traits. If there is an existing identity, using PUT will update the existing identity with the data from the request.
+
+It has a limit of 100 identities per request.
+
+
+<Heading
+  id={"request"}
+  as={"h2"}
+  className={"openapi-tabs__heading"}
+  children={"Request"}
+>
+</Heading>
+
+<ParamsDetails
+  parameters={undefined}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={{"content":{"application/json":{"schema":{"type":"object","example":{},"properties":{"data":{"type":"array","items":{"type":"object","properties":{"traits":{"type":"array","items":{"type":"object","properties":{"trait_key":{"type":"string","example":"Name"},"trait_value":{"oneOf":[{"type":"string","example":"B.A. Baracus"},{"type":"number","example":42},{"type":"boolean","example":true}],"nullable":true}},"title":"Trait"}},"identifier":{"type":"string"}},"title":"IdentitiesRequestData"}}},"title":"BulkIdentitiesData"}}}}}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"type":"string","description":"Number of identities must not be more than 100"}}}},"403":{"description":"Forbidden","content":{"text/plain":{"schema":{"type":"string","description":"Organisation is disabled from serving flags."}}}},"404":{"description":"Not Found","content":{"text/plain":{"schema":{"type":"string","description":"Environment not found"}}}}}}
+>
+
+</StatusCodes>
+
+
+

docs/docs/edge-api/edge-api.info.mdx

@@ -0,0 +1,76 @@
+---
+id: edge-api
+title: "Edge API"
+description: ""
+sidebar_label: Introduction
+sidebar_position: 0
+hide_title: true
+custom_edit_url: null
+---
+
+import ApiLogo from "@theme/ApiLogo";
+import Heading from "@theme/Heading";
+import SchemaTabs from "@theme/SchemaTabs";
+import TabItem from "@theme/TabItem";
+import Export from "@theme/ApiExplorer/Export";
+
+<span
+  className={"theme-doc-version-badge badge badge--secondary"}
+  children={"Version: 1"}
+>
+</span>
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Edge API"}
+>
+</Heading>
+
+
+
+
+
+<div
+  style={{"marginBottom":"2rem"}}
+>
+  <Heading
+    id={"authentication"}
+    as={"h2"}
+    className={"openapi-tabs__heading"}
+    children={"Authentication"}
+  >
+  </Heading><SchemaTabs
+    className={"openapi-tabs__security-schemes"}
+  >
+    <TabItem
+      label={"API Key: EnvironmentKey"}
+      value={"EnvironmentKey"}
+    >
+
+
+
+
+      <div>
+        <table>
+          <tbody>
+            <tr>
+              <th>
+                Security Scheme Type:
+              </th><td>
+                apiKey
+              </td>
+            </tr><tr>
+              <th>
+                Header parameter name:
+              </th><td>
+                X-Environment-Key
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </TabItem>
+  </SchemaTabs>
+</div>
+

docs/docs/edge-api/get-flags.api.mdx

@@ -0,0 +1,71 @@
+---
+id: get-flags
+title: "Get flags"
+description: "Retrieve the flags for an environment."
+sidebar_label: "Get flags"
+hide_title: true
+hide_table_of_contents: true
+api: eJztVV1P2zAU/SuWn9MG0J76VgmGEBJMwKRJqKrc5CYxc2xj32RUUf77fOM0hI6hPe1hWl+q+H74nHPt446jKD1fPfKLvAS2/nLFNwnPwWdOWpRG8xW/A3QSWmBYAStUyGeFcUxoBrqVzugaNC55wq1wogYERw07Lqn4uQG3DzEdIuGzAIGNg7DgswpqwVcdx72lkNQIJTjeJ9zBcyMd5HxVCOXhGNDVOTNFRBPbMTSskCrsTMiW7MYgoRWYMFkw60wrc8gT5sBboz0w6ZlgXupSATO7J8hCpjZInIRzYr/k/YZgxHRPKM9OTujvLZLb68AkMwG5RooKa5XMBEXTJ08p3Yyo0XBbDNKMlIe9QgeJUPuZFBESKeqMBYcyQgAtdopUmRJ3xigQmjQbpdh6FAjbVqgG3t3Th2HqMvSGF1FbNcBYOKiDZIvApJDlIhb3yVSjm3oXJjOr+XQ2Cx9QzOLoGiAJdaMUgR5XJpgDB4nq7Zn4mL7M3zktNCWR32q1j1scYRzP3UfsfWV+bCtwZrsTWscDGLM/qrp/WN+cr+/OeR9+ycTlc+RyT0MIoeT/SP+xkW76GA0+V5mAnpcw0BJYhY90sEdyN3DtwQcbp0KoQrR+laYQfHYprFwOqbXEapmZOg0raXvKj61ucmVS3kPWOIn7oevFq/deAy1t5in3ZDpR4+PEV/exkhaSaNRV0HwQf3Tqb4tZ4YISibbUhZkPesKXcOIbQZ+S3tZ4rMXggGPHS0B20OcNy+7VQv/8sRlJILxgapWQw40ZpO7GaTzyuFuQpQpgaKHrdsLDV6f6npbj40Rq5tKPF/G9F2cO8G88Pr9h953GN7tboyPw4XC0wsl4LcNJSA7jJG6xbJ1lYHFW9ctbRV2mY3158RAG/hNN1chh
+sidebar_class_name: "get api-method"
+info_path: edge-api/edge-api
+custom_edit_url: null
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Get flags"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"get"}
+  path={"/flags"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Retrieve the flags for an environment.
+
+<Heading
+  id={"request"}
+  as={"h2"}
+  className={"openapi-tabs__heading"}
+  children={"Request"}
+>
+</Heading>
+
+<ParamsDetails
+  parameters={[{"in":"query","name":"feature","schema":{"type":"integer"},"required":false,"description":"ID of the feature to filter for. Note that, if provided, response is a single object, not an array."}]}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={undefined}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"enabled":{"type":"boolean"},"feature_state_value":{"oneOf":[{"type":"string","example":"a-remote-config-value"},{"type":"number","example":42},{"type":"boolean","example":true}],"nullable":true},"feature":{"title":"feature","type":"object","properties":{"id":{"type":"integer","readOnly":true,"example":42},"name":{"type":"string","example":"show_hero_banner"},"type":{"type":"string","example":"STANDARD"}}}},"title":"FeatureState"}},{"type":"object","properties":{"enabled":{"type":"boolean"},"feature_state_value":{"oneOf":[{"type":"string","example":"a-remote-config-value"},{"type":"number","example":42},{"type":"boolean","example":true}],"nullable":true},"feature":{"title":"feature","type":"object","properties":{"id":{"type":"integer","readOnly":true,"example":42},"name":{"type":"string","example":"show_hero_banner"},"type":{"type":"string","example":"STANDARD"}}}},"title":"FeatureState"}]}}}}}}
+>
+
+</StatusCodes>
+
+
+