Browse Source

feat(tool): Generate specs from source code

pull/465/head
jld3103 1 year ago
parent
commit
e0bd715d2d
No known key found for this signature in database
GPG Key ID: 9062417B9E8EB7B3
  1. 3
      .gitmodules
  2. 1
      external/nextcloud-openapi-extractor
  3. 2
      external/nextcloud-server
  4. 4655
      packages/nextcloud/lib/src/api/core.openapi.json
  5. 1
      packages/nextcloud/lib/src/api/news.openapi.json
  6. 22
      packages/nextcloud/lib/src/api/notes.openapi.json
  7. 63
      packages/nextcloud/lib/src/api/notifications.openapi.json
  8. 4368
      packages/nextcloud/lib/src/api/provisioning_api.openapi.json
  9. 66
      packages/nextcloud/lib/src/api/settings.openapi.json
  10. 778
      packages/nextcloud/lib/src/api/theming.openapi.json
  11. 1
      packages/nextcloud/lib/src/api/uppush.openapi.json
  12. 1439
      packages/nextcloud/lib/src/api/user_status.openapi.json
  13. 30
      tool/generate-specs.sh

3
.gitmodules vendored

@ -19,3 +19,6 @@
[submodule "external/flathub-shared-modules"]
path = external/flathub-shared-modules
url = https://github.com/flathub/shared-modules.git
[submodule "external/nextcloud-openapi-extractor"]
path = external/nextcloud-openapi-extractor
url = https://github.com/nextcloud/openapi-extractor

1
external/nextcloud-openapi-extractor vendored

@ -0,0 +1 @@
Subproject commit 5940a175e352d3cf7780e1c50dd572dfe04523b3

2
external/nextcloud-server vendored

@ -1 +1 @@
Subproject commit add4e4365a4040d2e4e6aa79c0d03c3edd78583c
Subproject commit 752299d063f8c82c329bd73b66ae7efc85ca1e2a

4655
packages/nextcloud/lib/src/api/core.openapi.json

File diff suppressed because it is too large Load Diff

1
packages/nextcloud/lib/src/api/news.openapi.json

@ -27,6 +27,7 @@
"basic_auth": []
}
],
"tags": [],
"components": {
"schemas": {
"OCSMeta": {

22
packages/nextcloud/lib/src/api/notes.openapi.json

@ -27,8 +27,30 @@
"basic_auth": []
}
],
"tags": [],
"components": {
"schemas": {
"Capabilities": {
"type": "object",
"required": ["notes"],
"properties": {
"notes": {
"type": "object",
"additionalProperties": true,
"properties": {
"api_version": {
"type": "array",
"items": {
"type": "string"
}
},
"version": {
"type": "string"
}
}
}
}
},
"OCSMeta": {
"type": "object",
"required": [

63
packages/nextcloud/lib/src/api/notifications.openapi.json

@ -23,12 +23,46 @@
}
],
"security": [
{
"bearer": []
},
{
"basic_auth": []
}
],
"tags": [],
"components": {
"schemas": {
"Capabilities": {
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"type": "object",
"additionalProperties": true,
"properties": {
"ocs-endpoints": {
"type": "array",
"items": {
"type": "string"
}
},
"push": {
"type": "array",
"items": {
"type": "string"
}
},
"admin-notifications": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"OCSMeta": {
"type": "object",
"required": [
@ -291,6 +325,10 @@
"basic_auth": {
"type": "http",
"scheme": "basic"
},
"bearer": {
"type": "http",
"scheme": "bearer"
}
}
},
@ -313,6 +351,11 @@
},
"delete": {
"operationId": "delete-all-notifications",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "",
@ -355,6 +398,11 @@
},
"delete": {
"operationId": "delete-notification",
"security": [
{
"bearer": []
}
],
"responses": {
"200": {
"description": "",
@ -372,6 +420,11 @@
"/ocs/v2.php/apps/notifications/api/v2/push": {
"post": {
"operationId": "register-device",
"security": [
{
"bearer": []
}
],
"parameters": [
{
"name": "pushTokenHash",
@ -414,6 +467,11 @@
},
"delete": {
"operationId": "remove-device",
"security": [
{
"bearer": []
}
],
"responses": {
"202": {
"description": "",
@ -440,6 +498,11 @@
}
],
"post": {
"security": [
{
"bearer": []
}
],
"operationId": "send-admin-notification",
"parameters": [
{

4368
packages/nextcloud/lib/src/api/provisioning_api.openapi.json

File diff suppressed because it is too large Load Diff

66
packages/nextcloud/lib/src/api/settings.openapi.json

@ -0,0 +1,66 @@
{
"openapi": "3.1.0",
"info": {
"title": "settings",
"version": "0.0.1",
"description": "Nextcloud settings",
"license": {
"name": "agpl",
"identifier": "AGPL-3.0-only"
}
},
"components": {
"securitySchemes": {
"basic_auth": {
"type": "http",
"scheme": "basic"
},
"bearer_auth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {}
},
"paths": {
"/index.php/settings/admin/log/download": {
"get": {
"operationId": "log_settings-download",
"summary": "download logfile",
"description": "This endpoint requires admin access",
"tags": [
"log_settings"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"responses": {
"200": {
"description": "",
"headers": {
"Content-Disposition": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
}
},
"tags": []
}

778
packages/nextcloud/lib/src/api/theming.openapi.json

@ -0,0 +1,778 @@
{
"openapi": "3.1.0",
"info": {
"title": "theming",
"version": "0.0.1",
"description": "Adjust the Nextcloud theme",
"license": {
"name": "agpl",
"identifier": "AGPL-3.0-only"
}
},
"components": {
"securitySchemes": {
"basic_auth": {
"type": "http",
"scheme": "basic"
},
"bearer_auth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"Background": {
"type": "object",
"required": [
"backgroundImage",
"backgroundColor",
"version"
],
"properties": {
"backgroundImage": {
"type": "string",
"nullable": true
},
"backgroundColor": {
"type": "string"
},
"version": {
"type": "integer",
"format": "int64"
}
}
},
"OCSMeta": {
"type": "object",
"required": [
"status",
"statuscode"
],
"properties": {
"status": {
"type": "string"
},
"statuscode": {
"type": "integer"
},
"message": {
"type": "string"
},
"totalitems": {
"type": "string"
},
"itemsperpage": {
"type": "string"
}
}
},
"PublicCapabilities": {
"type": "object",
"required": [
"theming"
],
"properties": {
"theming": {
"type": "object",
"required": [
"name",
"url",
"slogan",
"color",
"color-text",
"color-element",
"color-element-bright",
"color-element-dark",
"logo",
"background",
"background-plain",
"background-default",
"logoheader",
"favicon"
],
"properties": {
"name": {
"type": "string"
},
"url": {
"type": "string"
},
"slogan": {
"type": "string"
},
"color": {
"type": "string"
},
"color-text": {
"type": "string"
},
"color-element": {
"type": "string"
},
"color-element-bright": {
"type": "string"
},
"color-element-dark": {
"type": "string"
},
"logo": {
"type": "string"
},
"background": {
"type": "string"
},
"background-plain": {
"type": "boolean"
},
"background-default": {
"type": "boolean"
},
"logoheader": {
"type": "string"
},
"favicon": {
"type": "string"
}
}
}
}
}
}
},
"paths": {
"/index.php/apps/theming/theme/{themeId}.css": {
"get": {
"operationId": "theming-get-theme-stylesheet",
"summary": "Get the CSS stylesheet for a theme",
"tags": [
"theming"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "plain",
"in": "query",
"description": "Let the browser decide the CSS priority",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "withCustomCss",
"in": "query",
"description": "Include custom CSS",
"schema": {
"type": "integer",
"default": 0
}
},
{
"name": "themeId",
"in": "path",
"description": "ID of the theme",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Stylesheet returned",
"content": {
"text/css": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/image/{key}": {
"get": {
"operationId": "theming-get-image",
"summary": "Get an image",
"tags": [
"theming"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "useSvg",
"in": "query",
"description": "Return image as SVG",
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "key",
"in": "path",
"description": "Key of the image",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Image returned",
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/manifest/{app}": {
"get": {
"operationId": "theming-get-manifest",
"summary": "Get the manifest for an app",
"tags": [
"theming"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "app",
"in": "path",
"description": "ID of the app",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name",
"short_name",
"start_url",
"theme_color",
"background_color",
"description",
"icons",
"display"
],
"properties": {
"name": {
"type": "string"
},
"short_name": {
"type": "string"
},
"start_url": {
"type": "string"
},
"theme_color": {
"type": "string"
},
"background_color": {
"type": "string"
},
"description": {
"type": "string"
},
"icons": {
"type": "array",
"items": {
"type": "object",
"required": [
"src",
"type",
"sizes"
],
"properties": {
"src": {
"type": "string",
"minLength": 1
},
"type": {
"type": "string"
},
"sizes": {
"type": "string"
}
}
}
},
"display": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/index.php/apps/theming/favicon/{app}": {
"get": {
"operationId": "icon-get-favicon",
"summary": "Return a 32x32 favicon as png",
"tags": [
"icon"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "app",
"in": "path",
"description": "ID of the app",
"required": true,
"schema": {
"type": "string",
"default": "core"
}
}
],
"responses": {
"200": {
"description": "Favicon returned",
"content": {
"image/x-icon": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/icon/{app}": {
"get": {
"operationId": "icon-get-touch-icon",
"summary": "Return a 512x512 icon for touch devices",
"tags": [
"icon"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "app",
"in": "path",
"description": "ID of the app",
"required": true,
"schema": {
"type": "string",
"default": "core"
}
}
],
"responses": {
"200": {
"description": "Touch icon returned",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/img/{app}/{image}": {
"get": {
"operationId": "icon-get-themed-icon",
"summary": "Get a themed icon",
"tags": [
"icon"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "app",
"in": "path",
"description": "ID of the app",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "image",
"in": "path",
"description": "image file name (svg required)",
"required": true,
"schema": {
"type": "string",
"pattern": "^.+$"
}
}
],
"responses": {
"200": {
"description": "Themed icon returned",
"content": {
"image/svg+xml": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/background": {
"get": {
"operationId": "user_theme-get-background",
"summary": "Get the background image",
"tags": [
"user_theme"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Background image returned",
"content": {
"*/*": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
}
}
}
},
"/index.php/apps/theming/background/{type}": {
"post": {
"operationId": "user_theme-set-background",
"summary": "Set the background",
"tags": [
"user_theme"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "value",
"in": "query",
"description": "Path of the background image",
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "color",
"in": "query",
"description": "Color for the background",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "type",
"in": "path",
"description": "Type of background",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Background set successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Background"
}
}
}
}
}
}
},
"/index.php/apps/theming/background/custom": {
"delete": {
"operationId": "user_theme-delete-background",
"summary": "Delete the background",
"tags": [
"user_theme"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Background"
}
}
}
}
}
}
},
"/ocs/v2.php/apps/theming/api/v1/theme/{themeId}/enable": {
"put": {
"operationId": "user_theme-enable-theme",
"summary": "Enable theme",
"tags": [
"user_theme"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "themeId",
"in": "path",
"description": "the theme ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Theme enabled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/apps/theming/api/v1/theme/{themeId}": {
"delete": {
"operationId": "user_theme-disable-theme",
"summary": "Disable theme",
"tags": [
"user_theme"
],
"security": [
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "themeId",
"in": "path",
"description": "the theme ID",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Theme disabled successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
}
},
"tags": [
{
"name": "theming",
"description": "Class ThemingController\nhandle ajax requests to update the theme"
}
]
}

1
packages/nextcloud/lib/src/api/uppush.openapi.json

@ -8,6 +8,7 @@
},
"version": "1.4.0"
},
"tags": [],
"paths": {
"/index.php/apps/uppush": {
"get": {

1439
packages/nextcloud/lib/src/api/user_status.openapi.json

File diff suppressed because it is too large Load Diff

30
tool/generate-specs.sh

@ -0,0 +1,30 @@
#!/bin/bash
set -euxo pipefail
cd "$(dirname "$0")/.."
rm -rf /tmp/nextcloud-neon
mkdir -p /tmp/nextcloud-neon
(
cd external/nextcloud-openapi-extractor
composer update && composer install
)
for path in core apps/provisioning_api apps/settings apps/theming apps/user_status; do
codename="$(echo $path | sed "s/^apps\///")"
./external/nextcloud-openapi-extractor/generate-spec "external/nextcloud-server/$path" "packages/nextcloud/lib/src/api/$codename.openapi.json" --first-status-code --first-content-type --openapi-version 3.1.0
done
./external/nextcloud-openapi-extractor/merge-specs \
--openapi-version 3.1.0 \
--core packages/nextcloud/lib/src/api/core.openapi.json \
--merged /tmp/nextcloud-neon/merged.json \
packages/nextcloud/lib/src/api/*.openapi.json
jq \
-s \
'.[0] * {paths: {"/ocs/v2.php/cloud/capabilities": {get: {responses: .[1].paths."/ocs/v2.php/cloud/capabilities".get.responses}}}}' \
packages/nextcloud/lib/src/api/core.openapi.json \
/tmp/nextcloud-neon/merged.json \
> /tmp/nextcloud-neon/core.json
cp /tmp/nextcloud-neon/core.json packages/nextcloud/lib/src/api/core.openapi.json
Loading…
Cancel
Save