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 !
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 !
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 !
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 !
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 !
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 !
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 !
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.
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>
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>
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>
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.
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
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
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>
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>
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.
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>
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
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.
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.
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.