Skip to content

Commit

Permalink
feat: brand new multiregion API doc client-side renderer with tryit e…
Browse files Browse the repository at this point in the history
…ditor code examples and merge of all microservice manifests into a single searchable+filterable page
  • Loading branch information
jeromefellus-sekoia committed Nov 28, 2024
1 parent 2d01430 commit 84ac4ad
Show file tree
Hide file tree
Showing 250 changed files with 8,398 additions and 168 deletions.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
169 changes: 151 additions & 18 deletions docs/developer/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,154 @@ template: overrides/openapi.html

# Sekoia.io API documentation

<div class="ui-spinner"></div>
<div id="openapi">
<section style="display:none;">
https://app.sekoia.io/api/v1/dashboard/swagger.json?context=public
https://app.sekoia.io/api/v1/telemetry/openapi.json?context=public
https://app.sekoia.io/api/v1/notebooks/openapi.json?context=public
https://app.sekoia.io/api/v1/sic/conf/swagger.json?context=public
https://app.sekoia.io/api/v1/swagger.json?context=public
https://app.sekoia.io/api/v1/ingest/swagger.json?context=public
https://app.sekoia.io/api/v1/sic/swagger.json?context=public
https://app.sekoia.io/api/v1/symphony/swagger.json?context=public
https://app.sekoia.io/api/v1/enricher/swagger.json?context=tip
https://app.sekoia.io/api/v1/swagger.json?context=public
https://app.sekoia.io/api/v2/asset-management/openapi.json?context=public
https://app.sekoia.io/api/v1/edl-gateway/openapi.json
https://app.sekoia.io/api/v2/inthreat/swagger.json?context=public
</section>
</div>
{!docs/developer/quickstart.md!}


<script>
window.onload = ()=> {
OpenAPIViewer.init({
title:"Sekoia.io API Documentation",
regions: [
"FRA1",
"FRA2",
"MCO1",
"UAE1",
],
urls: [
"https://app.sekoia.io/api/v1/dashboard/swagger.json?context=public",
"https://app.sekoia.io/api/v1/telemetry/openapi.json?context=public",
"https://app.sekoia.io/api/v1/notebooks/openapi.json?context=public",
"https://app.sekoia.io/api/v1/sic/conf/swagger.json?context=public",
"https://app.sekoia.io/api/v1/swagger.json?context=public",
"https://app.sekoia.io/api/v1/ingest/swagger.json?context=public",
"https://app.sekoia.io/api/v1/sic/swagger.json?context=public",
"https://app.sekoia.io/api/v1/symphony/swagger.json?context=public",
"https://app.sekoia.io/api/v1/enricher/swagger.json?context=tip",
"https://app.sekoia.io/api/v2/asset-management/openapi.json?context=public",
"https://app.sekoia.io/api/v1/edl-gateway/openapi.json",
"https://app.sekoia.io/api/v2/inthreat/swagger.json?context=public",
],
menu:[
{
name: "User",
tags: [
"User Authentication",
"me",
"mfa", // TODO: split 'mfa' into administration and self
"permissions",
],
},
{
name: "Workspace",
tags: [
"customers", // TODO deprecated, get rid of it
"communities",
"api-keys",
"licenses",
"invitations",
"plans",
"sub-communities",
"avatars",
"users", // TODO set this tag on all user administration stuff
"roles",
],
},
{
name: "Intelligence",
tags: [
"Observables",
"CTI Objects",
"Bundles",
"Collections",
"Exports",
"Outgoing Feeds",
"Graphs",
"MISP",
"Objects",
"Observable relationships",
"Indicators",
"Images",
"support",
"Labels",
"Kill Chains",
],
},
{
name: "Collect",
tags: [
"Intakes",
"Assets",
"Atoms",
"Intakes by status",
"Intakes errors and warnings",
"Intakes lag and processing lag",
"formats",
"IOC Collections",
],
},

{
name: "Detection rules",
tags: [
"Rules",
"datasources",
"generation-modes",
"rules-catalog",
"alert-filter", // TODO: to create, this tag doesn't exist yet
],
},
{
name: "Alerts",
tags: [
"Alert",
"Alert Entities",
"Alert Rules",
"Alert Sources and Targets",
"Countermeasures",
"Cyber Kill Chain",
"Stats",
"Alert Status",
"Alert Type",
],
},
{
name: "Cases",
tags: [
"Case",
"Comments",
"Statistics",
"Enrichers",
"Callbacks",
"Services",
"Tasks",
],
},
{
name: "Playbooks",
tags: [
"Playbook actions telemetry",
"modules",
"Action Runs",
"Actions",
"Changes",
"Connector Configurations",
"Connectors",
"Module Configurations",
"Modules",
"Node Runs",
"Playbooks Runs",
"Playbooks",
"Trigger Configurations",
"Triggers",
],
},
{
name: "AI assistant", // TODO: Make that private
tags: [
"Roy tokens use telemetry",
],
},
]
})
};
</script>
17 changes: 17 additions & 0 deletions docs/javascript/openapi-viewer.min.js

Large diffs are not rendered by default.

16 changes: 12 additions & 4 deletions docs/javascript/openapi.js → docs/javascript/openapi.js.bak
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,10 @@ const X_TAG_GROUPS = [
"Stats",
"Alert Status",
"Alert Type",
]
},{
name:"Cases",
],
},
{
name: "Cases",
tags: [
"Case",
"Comments",
Expand All @@ -94,7 +95,7 @@ const X_TAG_GROUPS = [
"Callbacks",
"Services",
"Tasks",
]
],
},
{
name: "Playbooks",
Expand Down Expand Up @@ -727,6 +728,13 @@ print(json.dumps(result, indent=4))
)
e.setAttribute("selected", true);
});

// Incorporate quickstart guide
const elApiInfo = document.querySelector(".api-content .api-info");
document.querySelectorAll("main article > *").forEach((x) => {
if (x.classList.contains("ui-spinner")) x.remove();
else if (x.id !== "openapi") elApiInfo.appendChild(x);
});
}

window.addEventListener("load", init_openapi_documentation);
2 changes: 1 addition & 1 deletion docs/stylesheets/openapi.css

Large diffs are not rendered by default.

24 changes: 24 additions & 0 deletions lib/openapi-viewer/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Sekoia.io OpenAPI Viewer library

This viewer library is a Sekoia.io custom instrumentation of [Redoc](https://github.com/Redocly/redoc), providing
* easier navigation in a large API doc using OpenAPI 3.1 tags and tagGroups
* client-side merging of several OpenAPI/Swagger manifests
* hosting region selector
* plans and permissions handling
* in-browser try-it editor

Any update to this library's code should be **compiled before commit**.
The compiled library [../openapi-viewer.js](../openapi-viewer.js) is versioned and pushed to this repo to keep our Documentation repo dependency-free.

If you need to modify the library's code please run
```bash
yarn
yarn build
```
to compile [../openapi-viewer.js](../openapi-viewer.js)

For best DX, you may use the webpack devserver via
```bash
yarn
yarn start
```
4 changes: 4 additions & 0 deletions lib/openapi-viewer/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
module.exports = {
presets: ["@vue/cli-plugin-babel/preset"],
plugins: ["@vue/babel-plugin-jsx"],
};
30 changes: 30 additions & 0 deletions lib/openapi-viewer/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"name": "openapi-viewer",
"version": "1.0.0",
"license": "MIT",
"scripts": {
"start": "vue-cli-service serve --host 127.0.0.1",
"build": "vue-cli-service build && cp -f dist/openapi-viewer.min.js ../../docs/javascript/openapi-viewer.min.js",
"lint": "vue-cli-service lint"
},
"dependencies": {
"@babel/core": "^7.19.3",
"@highlightjs/vue-plugin": "^2.1.0",
"@vue/babel-plugin-jsx": "^1.1.1",
"chartjs-adapter-moment": "^1.0.1",
"codemirror": "^5.49.2",
"dompurify": "^3.2.1",
"marked": "^15.0.2",
"moment": "^2.30.1",
"vue": "^3.2.41",
"vue-router": "^4.1.5",
"vue-tippy": "^6.5.0"
},
"devDependencies": {
"@vue/cli-plugin-babel": "^5.0.8",
"@vue/cli-service": "^5.0.8",
"@vue/compiler-sfc": "^3.2.41",
"sass": "^1.55.0",
"sass-loader": "^13.1.0"
}
}
2 changes: 2 additions & 0 deletions lib/openapi-viewer/src/Code.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/** A Vue component using highlightjs for syntax highlighting of code blocks */
export const Code = ({ src, lang }) => <highlightjs language={lang} code={src} />
33 changes: 33 additions & 0 deletions lib/openapi-viewer/src/Dropdown.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
import { ref } from "vue";
import { useTippy } from "vue-tippy";
import 'tippy.js/animations/shift-away.css';
import "./Dropdown.scss"

/** A Dropdown Vue component */
export const Dropdown = {
props: ["button", "class", "content"],
setup(props, { slots }) {
const target = ref(null)
const { show } = useTippy(target, {
trigger: "manual",
interactive: true,
placement: "bottom-start",
offset: [0, 4],
animation: "shift-away",
maxWidth: 'none',
content: {
setup() {
return () => <div class={props.class}>
{props.content}
</div>
}
},
});

return () => {
return <button ref={target} class='dropdown-button' class={props.class} onClick={() => show()}>
{props.button}
</button>
}
}
}
3 changes: 3 additions & 0 deletions lib/openapi-viewer/src/Dropdown.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.dropdown-button {
cursor: pointer;
}
5 changes: 5 additions & 0 deletions lib/openapi-viewer/src/Error.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
/** Vue component to render documentation for an error code */
export const Error = ({ code, response }) => <div class="response error">
<span class='status-code'>{code}</span>
<div>{response?.description}</div>
</div>
Loading

0 comments on commit 84ac4ad

Please sign in to comment.