Commit Graph
37 Commits
Author SHA1 Message Date
Lauri Ojansivu 4d5fe63fc4 The name is WeKan in the REST API documentation.
openapi/generate_openapi.py's header and the models' JSDoc said
"Wekan REST API", "extend Wekan", "a production Wekan server" and
"in the Wekan board", so every release's API pages on wekan.fi failed
its brand-spelling check (v12.95-v12.97 did). The generator, the model
comments and public/api/wekan.yml now say WeKan, and
tests/openapiBrandSpelling.test.cjs checks the generated file, the
generator header and every model JSDoc block.

Thanks to xet7 !
2026-11-06 19:24:04 +02:00
Lauri Ojansivu 582a22c291 Fix GitHub code scanning code-quality findings.
Real faults: a card's original-position description formatted a promise
because it did not await the history; the attachment swipe distances and
two drag-scroll locals were undeclared globals; a file that cannot be read
during a GridFS upload left the upload open; api.py called exit() instead of
sys.exit(); a rules test redefined a property and a security-log test kept
an unreachable branch. Also 31 missing semicolons, unused imports in the
card details, exporters and attachment API, unused Python imports, and
comments on empty except clauses. The list-sync scanner test cut its source
at the last Meteor.startup, which the new index startup of #6855 had moved.

Thanks to GitHub CodeQL and xet7 !
2026-11-02 14:15:02 +02:00
Lauri Ojansivu ed4a3a86a1 API docs: a spread in a schema no longer stops the release.
The bump job of release-all.yml stopped in openapi/generate_openapi.py with
"AttributeError: 'NoneType' object has no attribute 'name'". Notification
delivery builds part of the Boards, Integrations, Settings and Users schemas
with `...deliverySchemaFields('notificationDelivery')`, and the generator
read the key of every schema property, which a spread does not have.

A spread is now documented as one optional object named by the helper's
first string argument - notificationDelivery on all four - and a spread with
no such name is skipped with a warning. The generated spec renders with
@redocly/cli. tests/openapiSchemaSpread.test.cjs runs the whole generator
when a Python with esprima is available, and fails on any schema spread in
models/ that would be left undocumented.

Thanks to xet7 !
2026-10-10 17:01:29 +03:00
Lauri Ojansivu 9c79602b64 Let the OpenAPI generator survive declarations without an initializer.
The release-all bump job stopped in openapi/generate_openapi.py with
"AttributeError: 'NoneType' object has no attribute 'type'": a REST
handler declares `let x;`, and the req.body walker read the declarator's
absent init. The walker now returns early on an absent node, and walks
the branches of a `?:` so fields read there (the board copy title,
among others) are documented again. downlevel_js also rewrites `||=`
and `&&=`, which esprima cannot parse and which made the generator skip
models/lib/importedAttachmentsByCard.js.

tests/openapiReqBodyWalker.test.cjs pins the guard, the ternary walk and
the rewrite, drives the walker on the shapes that broke it, and runs the
whole generator asserting no file is skipped.

Thanks to xet7 !
2026-09-29 22:45:14 +03:00
Lauri Ojansivu 8ae15efffb Fix Node suite failures after calendar and translation updates
Restore backend configuration parity, resolve static calendar enum imports in OpenAPI generation, and parse Unicode property escapes without executing JavaScript. Preserve logical popup anchors and physical dragging. Protect reviewed source terms during filling, restore native examples and labels, and update stale guards while retaining the explicit unresolved Sardinian review. Add enum, dragging and filling regression coverage.
2026-09-13 14:06:01 +03:00
Lauri Ojansivu c64d3454ac Add REST API for Board Settings / Board View, and OpenAPI blocks for the card settings routes.
GET /api/boards/:boardId/boardViewSettings answers which entries of the
Board View menu a board offers, which one it opens in, separately for a
public and a private board, and the menu order - in the normalised shape the
menu renders with: every view once with both showOnPublic and showOnPrivate
explicit, the two defaults resolved (missing or unknown reads as Swimlanes),
boardViewOrder made whole, and `keys` listing the known views. Board access.

PUT /api/boards/:boardId/boardViewSettings takes any subset of
boardViewSettings, defaultPublicBoardView, defaultPrivateBoardView and
boardViewOrder, through the same pure modifiers the popup's clicks apply
(showBoardViewModifier, defaultBoardViewModifier, normalizeBoardViewOrder),
now composed by boardViewSettingsRequest() in models/lib/boardViewSettings.js:
a default is always shown on its side, hiding a side's current default is a
400 (set another default first - or in the same request, since defaults are
applied before the show flags), an unknown view key anywhere in the body is a
400 and nothing of that request is written, and the order is normalised so the
menu lists every view exactly once. Board admin (or site admin), the same
check as cardFieldOrder. Both answer boardViewSettingsSnapshot().

The existing GET/PUT /api/boards/:boardId/cardSettings routes get the JSDoc
@operation blocks the OpenAPI generator reads (get_board_card_settings,
update_board_card_settings), so the hand-written copy in
openapi/extra_paths.yml - which now duplicated the operationId - is removed.
public/api/wekan.yml and wekan.html are regenerated with the release
workflow's own commands: 158 operations. docs/API/REST-API.md documents both
endpoints with curl examples, and docs/Features/Board/Board-View-Settings.md
links to them.

tests/restApiNewFeatureRoutes.test.cjs pins the four routes to their method,
path, @operation and auth check, that the PUT writes only the helper's $set,
the snapshot's shape, the request helper's positive cases (setting a default
shows it, one request may move the default and hide the old one, the order is
normalised, the input board is not mutated) and negatives (unknown view key in
the order, the settings or a default; hiding a side's default; malformed
bodies; a partly-invalid body applies nothing), and that the generated and the
committed spec carry the four operations exactly once with the old
edit_board_card_settings gone.

Thanks to xet7 !
2026-09-11 21:18:35 +03:00
Lauri Ojansivu bbcd98d9d8 Add REST API for attachment soft delete and restore, Admin Panel Problems, OAuth login provider and passwordless settings, card field order and pausing a rule.
Every feature of the recent releases that had a UI but no endpoint, on the
same server-side code the UI uses:

- DELETE /api/boards/:boardId/attachments/:attachmentId soft-deletes,
  POST .../attachments/:attachmentId/restore restores, and
  GET /api/boards/:boardId/attachments/deleted lists what is restorable -
  all through the attachments.softDelete / attachments.restore methods the
  card and the card history use, run as the request's user. No hard delete.
- GET /api/admin/problems (the Problems status overview plus the new-problem
  count per stream), GET /api/admin/problems/:stream (one page, with
  limit/skip/search) and POST /api/admin/problems/:stream/acknowledge,
  through the admin-only eventLog* methods the Admin Panel pages call.
- GET /api/admin/oauth-providers, PUT /api/admin/oauth-providers/:providerKey
  and PUT /api/admin/passwordless, through saveOauthProviderSettings,
  savePasswordlessSettings and getOauthProviderConfigSources. A provider's
  secret is reported only as { source, hasValue }, never its value.
- GET/PUT /api/boards/:boardId/cardFieldOrder, normalised with the same
  applyCardFieldOrder() the card renders with.
- PUT /api/boards/:boardId/rules/:ruleId accepts `enabled` to pause and
  resume a rule, and GET reports it.

The OpenAPI generator is fixed on the way: server/models/boards.js has had a
bare `catch {` since v11.67, the esprima parser cannot read that, and a parse
failure was silently skipped - so public/api/wekan.yml has shipped WITHOUT
the whole Boards API since then. It now downlevels `catch {` and
`for await (`, warns when a file cannot be parsed, and no longer emits an
empty sub-schema for a primitive array-element marker such as
`wipLimitGroups.$.listIds.$`, which made the spec unparseable YAML.
public/api/wekan.yml and wekan.html are regenerated with the release
workflow's own commands: 156 operations, up from 122.

tests/restApiNewFeatureRoutes.test.cjs pins every new route to its method,
path, @operation block and authentication check, that the OAuth endpoints
never mention a secret outside the input whitelist, the generator's two
fixes, that the generated and the committed spec carry the Boards API and the
new operations, and - as the negative sweep - that no route in models/ or
server/models/ lacks an authentication check.

Thanks to xet7 !
2026-09-11 21:18:35 +03:00
Lauri Ojansivu cfaf71d22e Fix the release bump job: the generated OpenAPI spec was not valid YAML.
The bump job of release-all.yml (.tools/wekan13, run 93672173482)
regenerates public/api/wekan.yml with openapi/generate_openapi.py and then
renders it with @redocly/cli, which stopped the release with
"Error: bad indentation of a mapping entry in public/api/wekan.yml
(1232:2)". A @param whose description continues on the next JSDoc lines -
models/exportCharts.js's chartKey, "one of dashboard, burndown, ...
controlChart, ..." - was emitted under `description: |` with only its
FIRST line indented; the continuation lines landed at column 1, which is
no longer inside the block scalar, so the whole spec failed to parse.
print_openapi_param now indents every line of the description.

The same job warned "unknown type object / allowed values: string,
number, boolean, integer, array, file" four times for the rules API's
trigger/action params. OpenAPI 2.0 has no `object` for a path/query/form
parameter; those are now emitted as `type: string` / `format: json`
(the REST API takes them as JSON in a string), and `object` no longer
warns.

Reproduced locally (PyYAML: "expected <block end>, but found '<scalar>'
... line 1232, column 2"); after the fix the spec parses and
`npx @redocly/cli build-docs` - the exact step that failed - renders it.
tests/openapiParamMultiline.test.cjs pins the emitter and, where python3
with PyYAML is available (it is in CI), parses the regenerated spec.

Thanks to xet7 !
2026-09-11 13:16:47 +03:00
Lauri Ojansivu 6acfb396e4 Confirm REST user deletion results
Use the database removal count to distinguish a confirmed deletion from a missing user and unexpected outcomes. Extend OpenAPI generation with repeatable response contracts, document the 200 and 404 bodies, and cover authorization, failures, generated documentation, and the live REST path.

Thanks to AhmedLukman and xet7 !

Integrates PR #6642.
2026-08-28 07:09:45 +03:00
Lauri OjansivuandClaude Opus 4.8 b4bbf2480a Add ICS import REST API + OpenAPI + api.py example (#6323)
Expose the iCalendar (.ics) import as a REST endpoint
POST /api/boards/:boardId/swimlanes/:swimlaneId/lists/:listId/ics (body { ics })
that reuses the shared import logic, requires board write access, and returns
{ created, cardIds }. Document it in the OpenAPI spec (openapi/extra_paths.yml,
spliced into public/api/wekan.yml) and add an 'importics' example command to
api.py. Note the new endpoint in the ChangeLog.

Note: OAUTH2_LOGOUT_ENDPOINT (the only new env var in the Upcoming changelog) is
already present in all deployment configs (Dockerfile, docker-compose.yml,
snap-src/bin/config, start-wekan.sh/.bat); rebuild-wekan.sh/.bat are dev-run
scripts with no OAUTH2 section, so nothing was added there.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:58:36 +03:00
Lauri OjansivuandClaude Opus 4.8 69236a9062 Fix duplicate mapping keys in generated OpenAPI spec breaking API docs
The Release All Platforms bump job regenerates public/api/wekan.yml via
openapi/generate_openapi.py and renders it with @redocly/cli, whose strict
YAML parser rejects duplicate mapping keys. The 3-level nested SimpleSchema
in models/attachmentStorageSettings.js (storageConfig.filesystem.enabled,
storageConfig.gridfs.enabled, ...) exposed two generator bugs:

- The sub-schema name was derived from only the first dotted path segment,
  collapsing filesystem.* and gridfs.* leaf keys (enabled/read/write) into a
  single mapping.
- The linear emitter reopened the parent schema header once per interleaved
  nested object.

Build sub-schema names from all leading path segments, and stable-sort dotted
properties so each sub-schema's fields stay contiguous and its header is
emitted once. Output is unchanged for existing 1- and 2-level schemas;
@redocly/cli now renders the spec successfully.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 16:09:16 +03:00
Lauri OjansivuandClaude Opus 4.8 17bb7c1264 Fix OpenAPI generator crash on template-literal route paths (release-all bump job)
releases/rebuild-docs.sh runs openapi/generate_openapi.py, which crashed with
"AttributeError: 'NoneType' object has no attribute 'rstrip'" because a route
path argument that is a template literal (e.g. WebApp.handlers.get(
`/api/boards/:boardId/export/${format}`, ...) in models/export.js) has no
Literal .value. Resolve template-literal paths (turning ${identifier} into a
:identifier path parameter) and skip any route whose path cannot be resolved
statically instead of crashing the whole release. The export/:format route now
documents as /api/boards/{board}/export/{format}.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-15 14:56:55 +03:00
Lauri Ojansivu f0bce67a3b More Import Export and Rules features.
Thanks to xet7 and Claude !
2026-06-15 04:07:33 +03:00
Lauri Ojansivu c71a97cba2 **Fixed OpenAPI REST API documentation generation**, which had been broken
since after WeKan v7.93 and only generated docs for the `login`/`register`
endpoints (2 operations) instead of the full API. The Meteor 3 migration moved
the REST routes from `models/*.js` (`JsonRoutes.add(...)`) into
`server/models/*.js` (`WebApp.handlers.get/post/put/delete(...)`) and
introduced optional chaining (`?.`) that the `esprima` Python parser cannot
read, so `openapi/generate_openapi.py` silently skipped every route file.
The generator now understands both routing styles, scans both `models/` and
`server/models/`, downlevels modern JS syntax so files parse, handles the
`type: Array` SimpleSchema idiom, and `releases/rebuild-docs.sh` works directly
with Python 3.12.x (PEP 668). The generated `public/api/wekan.yml` /
`wekan.html` now cover the full API again (89 operations / 61 paths).
Thanks to Claude.

**Documented the attachment / file REST API in the OpenAPI docs** — file
upload, download, info, listing a board's files, copy, move and delete (the
`/api/attachment/*` endpoints registered via `WebApp.handlers.use()`, which the
generator cannot auto-discover) are now documented in `openapi/extra_paths.yml`
and injected into the generated docs, including their authentication and
permission requirements. Thanks to Claude.

**Security: attachment write operations in the REST/DDP API now require board
write access, not just membership (CWE-862, CWE-639).** Both attachment API
implementations (`server/routes/attachmentApi.js` HTTP routes and
`server/attachmentApi.js` Meteor methods) gated upload / copy / move / delete
on `board.hasMember()`, which is true for any active member regardless of role.
This let read-only, comment-only, no-comments, worker and assigned-only board
members add, copy, move and delete attachments through the API — actions the UI
forbids for those roles. They now require board write access (global site
admins still allowed); read operations (download / list / info) keep
membership-level access. Added security tests in
`server/lib/tests/attachmentApi.tests.js`. Thanks to Claude.

**The attachment copy API now honours the admin "Admin Panel / Attachments"
API transfer limits.** Copying an attachment creates a new attachment but
skipped the `apiUploadBlocked` / `apiUploadMaxBytes` checks that upload
enforces; copy now respects them in both API implementations. Thanks to Claude.

**SVG image uploads are now sanitized instead of rejected.** Uploaded SVGs
(attachments and avatars) are cleaned in place in `onAfterUpload` via the new
`models/lib/sanitizeSvg.js`, which removes JavaScript (`<script>`, inline
`on*=` event handlers, `javascript:`/`vbscript:` URIs, `<foreignObject>` /
`<iframe>` / `<object>` / `<embed>` and similar active content) and XML loops
(`<!DOCTYPE>` / `<!ENTITY>` entity-expansion / XXE constructs and
`<?xml-stylesheet?>`), so SVG images can be uploaded safely.

Thanks to Claude.
2026-06-05 23:44:04 +03:00
Lauri Ojansivu 0fdf45e847 Updated release scripts.
Thanks to xet7 !
2026-03-27 20:48:39 +02:00
Lauri Ojansivu 37c5436087 v8.02 2025-10-14 11:58:14 +03:00
Lauri Ojansivu 6592102e8f v8.02 2025-10-14 11:56:11 +03:00
Yang, Bo f399b5119f feat: enhance API documentation and add board-related endpoints
Previously, boards.js contains a `?.` operator, which is not supported by esprima, therefore boards.js is skipped.

This PR fixes the API generation for borads.js by removing `?.`.

See https://github.com/jquery/esprima/issues/2112
2025-06-23 20:01:38 +00:00
Yang, Bo e14a3f9c2d fix: properly document /users/login 2025-06-12 02:18:19 +00:00
Lauri Ojansivu a2911bc9c3 Fixed building OpenAPI docs.
Thanks to xet7 !

Fixes #5512
2025-03-15 19:32:16 +02:00
Benjamin Tissoires 73a170a388 openapi: fix breakage introduced with blank return
Introduced by commit f8ef2e33de ("cards.js Added a control to check
error if card is not updated"), a blank return was added at line 3914.

The generate_openapi script assumed a return statement always has an
argument, and this was crashing.

Fixes #5320
2024-02-22 16:31:11 +01:00
Benjamin Tissoires d7243bba77 openapi: also ignores ThrowStatement
This gives an error in the resulting file, which makes it not OpenAPI
compatible (not yaml actually).

Fixes #4917

Signed-off-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>
2023-05-09 10:13:23 +02:00
Benjamin Tissoires ebe39771a6 openapi: actually catch the error when esprima fails at parsing the file
39f8a138d7 added a try/except around esprima to catch any hard error
from the parsing, but the returned value was not checked.

We now have the file models/exportExcel.js which gives us an unexpected
symbol on line 3 (not sure why it is not happy), but that fails the
generation of the doc entirely.

Fixes #3884

Signed-off-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>
2021-07-01 10:23:29 +02:00
Benjamin Tissoires ae30b1220a openapi: better handle nested schemas
there is a 2 levels schemas in profile.notifications.

The code previously assumed we could only have one level, and so was not
producing the correct UsersProfileNotifications.

Fix that by being more generic in the way we retrieve the nested
subschemas.
2021-04-27 10:44:27 +02:00
Benjamin Tissoires 39f8a138d7 openapi: rework the allowedValues to allow for imported variables
Previously I was assuming all variables were declared in the same file.
Turns out that imports exists too, and we need to recurse one more time
in those imports./

Also "clean" up a bit the function to do the parsing in 2 steps:
- first find out the actual matching node in js
- then convert it based on its type
rinse wash repeat.

Signed-off-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>
2021-04-14 11:32:03 +02:00
Benjamin Tissoires 2c1f40357d Fix openapi docs generation
esprima-python is now safe to use
(https://github.com/Kronuz/esprima-python/pull/12)

And there was a new ArrowFunctionExpression used in db666eec65
that broke the python script
2021-03-26 18:41:34 +01:00
Lauri Ojansivu 0bb3b67075 Fixed generating API docs and Wekan Custom Fields REST API.
Thanks to xet7 !
2021-03-07 17:57:24 +02:00
Benjamin Tissoires e1ffe943c8 openapi: also consider Object type as valid
Not sure if this will end up in a correct openapi file, but the docs
are correctly generated, so... meh.
2020-06-17 05:40:38 +02:00
Benjamin Tissoires 431d884e83 openapi: fix jsdoc/operation matching
The script was considering that the operation
associated to a jsdoc was declared on the line
just after the end of the jsdoc.

Turns out that adding new lines makes the code
clearer, but the python script was then ignoring
some jsdocs.

Change the behaviour to consider that the jsdoc
associated with an operation is the last one
declared after the end of the previous operation.

Fixes #3169
2020-06-17 05:15:39 +02:00
Benjamin Tissoires 3f059ec1e0 generate_openapi: fix enums when they are declared as const
Fixes: #2781
2019-11-05 12:58:06 +01:00
Benjamin Tissoires 8cb3974eff generate_openapi: print a more useful error
...when we can not parse a SchemaProperty
2019-11-05 12:54:58 +01:00
Benjamin Tissoires 7d62d0920c generate_openapi: add a little bit more verbosity when we get an Error 2019-11-05 12:01:04 +01:00
Benjamin Tissoires b787854289 generate_openapi.py: use the logging module
Instead of dealing with custom writes to stderr, it's always better
to rely on standard libraries.
2019-11-05 11:06:40 +01:00
Benjamin Tissoires 1eea102f26 openAPI: also handle export statement in the scripts
The files are actually modules, not plain scripts, and thus we are allowed
to use `export`. Without `parseModule`, the script would silently fail
when parsing `export.js` and the export function will not be present.
2019-05-14 10:10:21 +02:00
Lauri Ojansivu 2969161afb - More whitelabeling.
Thanks to xet7 !
2019-03-21 20:27:21 +02:00
Benjamin Tissoires 8be7eec2ca openapi: make the code python 3.5 compatible
It is common to use Ubuntu 16.04 to build snaps. For example,
the official docker container to build snaps is using this old
distribution.

However, Ubuntu 16.04 ships Python 3.5.X which is not compatible
with the f-strings in generate_openapi.py. This is sad, because
we need to use the `.format()` syntax to make it compatible.
2019-01-18 17:03:12 +01:00
Benjamin Tissoires 49d3eb5a3f Add OpenAPI description of the REST API
The API is generated by a custom script that parses the models directory.
Once the API is generated, tools like https://editor.swagger.io/ or
Python bravado can parse the file and generate a language friendly API.

Note that the tool generate an OpenAPI 2.0 version because bravado
doesn't handle OpenAPI 3.0.

The script also parses the JSDoc with a custom parser to allow
customization of the description of the fields.
2019-01-18 17:01:11 +01:00