starred/planka
1
0
Fork 0
mirror of https://github.com/plankanban/planka.git synced 2025-12-22 01:11:29 +03:00
Code Issues 418 Packages Projects Releases 12 Wiki Activity

docs: Add full Swagger JSDoc coverage

Browse Source
This commit is contained in:
Maksim Eltyshev
2025-09-08 16:20:27 +02:00
parent e6b4c33542
commit 5ad3134519
128 changed files with 7610 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
server/api/controllers/access-tokens/accept-terms.js
View File

@@ -3,6 +3,92 @@
* Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
*/
/**
* @swagger
* /api/access-tokens/accept-terms:
* post:
* summary: Accept terms and conditions
* description: Accept terms during the authentication flow. Converts the pending token to an access token.
* tags:
* - Access Tokens
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - pendingToken
* - signature
* properties:
* pendingToken:
* type: string
* maxLength: 1024
* description: Pending token received from the authentication flow
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
* signature:
* type: string
* minLength: 64
* maxLength: 64
* description: Terms signature hash based on user role
* example: 940226c4c41f51afe3980ceb63704e752636526f4c52a4ea579e85b247493d94
* responses:
* 200:
* description: Terms accepted successfully
* content:
* application/json:
* schema:
* type: object
* required:
* - item
* properties:
* item:
* type: string
* description: Access token for API authentication
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ5...
* 400:
* $ref: '#/components/responses/ValidationError'
* 401:
* description: Invalid pending token
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_UNAUTHORIZED
* message:
* type: string
* description: Error message
* example: Invalid pending token
* 403:
* description: Authentication restriction
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_FORBIDDEN
* message:
* type: string
* enum:
* - Invalid signature
* - Admin login required to initialize instance
* description: Specific error message
* example: Invalid signature
*/
const { getRemoteAddress } = require('../../../utils/remote-address');
const { AccessTokenSteps } = require('../../../constants');

100
server/api/controllers/access-tokens/create.js
View File

@@ -3,6 +3,106 @@
* Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
*/
/**
* @swagger
* /api/access-tokens:
* post:
* summary: User login
* description: Authenticates a user using email/username and password. Returns an access token for API authentication.
* tags:
* - Access Tokens
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - emailOrUsername
* - password
* properties:
* emailOrUsername:
* type: string
* maxLength: 256
* description: Email address or username of the user
* example: john.doe@example.com
* password:
* type: string
* maxLength: 256
* description: Password of the user
* example: SecurePassword123!
* withHttpOnlyToken:
* type: boolean
* description: Whether to include an HTTP-only authentication cookie
* example: true
* responses:
* 200:
* description: Login successful
* content:
* application/json:
* schema:
* type: object
* required:
* - item
* properties:
* item:
* type: string
* description: Access token for API authentication
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
* headers:
* Set-Cookie:
* description: HTTP-only authentication cookie (if withHttpOnlyToken is true)
* schema:
* type: string
* example: httpOnlyToken=29aa3e38-8d24-4029-9743-9cbcf0a0dd5c; HttpOnly; Secure; SameSite=Strict
* 400:
* $ref: '#/components/responses/ValidationError'
* 401:
* description: Invalid credentials
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_UNAUTHORIZED
* message:
* type: string
* enum:
* - Invalid credentials
* - Invalid email or username
* - Invalid password
* description: Specific error message
* example: Invalid credentials
* 403:
* description: Authentication restriction
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_FORBIDDEN
* message:
* type: string
* enum:
* - Use single sign-on
* - Terms acceptance required
* - Admin login required to initialize instance
* description: Specific error message
* example: Use single sign-on
*/
const bcrypt = require('bcrypt');
const { isEmailOrUsername } = require('../../../utils/validators');

26
server/api/controllers/access-tokens/delete.js
View File

@@ -3,6 +3,32 @@
* Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
*/
/**
* @swagger
* /api/access-tokens:
* delete:
* summary: User logout
* description: Logs out the current user by deleting the session and access token. Clears HTTP-only cookies if present.
* tags:
* - Access Tokens
* responses:
* 200:
* description: Logout successful
* content:
* application/json:
* schema:
* type: object
* required:
* - item
* properties:
* item:
* type: string
* description: Revoked access token
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
* 401:
* $ref: '#/components/responses/Unauthorized'
*/
module.exports = {
async fn() {
const { currentSession } = this.req;

150
server/api/controllers/access-tokens/exchange-with-oidc.js
View File

@@ -3,6 +3,156 @@
* Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
*/
/**
* @swagger
* /api/access-tokens/exchange-with-oidc:
* post:
* summary: Exchange OIDC code for access token
* description: Exchanges an OIDC authorization code for an access token. Creates a user if they do not exist.
* tags:
* - Access Tokens
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - nonce
* properties:
* code:
* type: string
* maxLength: 2048
* description: Authorization code from OIDC provider
* example: abc123def456ghi789
* nonce:
* type: string
* maxLength: 1024
* description: Nonce value for OIDC security
* example: random-nonce-123456
* withHttpOnlyToken:
* type: boolean
* description: Whether to include HTTP-only authentication cookie
* example: true
* responses:
* 200:
* description: OIDC exchange successful
* content:
* application/json:
* schema:
* type: object
* required:
* - item
* properties:
* item:
* type: string
* description: Access token for API authentication
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
* 400:
* $ref: '#/components/responses/ValidationError'
* 401:
* description: OIDC authentication error
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_UNAUTHORIZED
* message:
* type: string
* enum:
* - Invalid code or nonce
* - Invalid userinfo configuration
* description: Specific error message
* example: Invalid code or nonce
* 403:
* description: Authentication restriction
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_FORBIDDEN
* message:
* type: string
* enum:
* - Terms acceptance required
* - Admin login required to initialize instance
* description: Specific error message
* example: Terms acceptance required
* 409:
* description: Conflict error
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_CONFLICT
* message:
* type: string
* enum:
* - Email already in use
* - Username already in use
* - Active users limit reached
* description: Specific error message
* example: Email already in use
* 422:
* description: Missing required values
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_UNPROCESSABLE_ENTITY
* message:
* type: string
* description: Error message
* example: Unable to retrieve required values (email, name)
* 500:
* description: OIDC configuration error
* content:
* application/json:
* schema:
* type: object
* required:
* - code
* - message
* properties:
* code:
* type: string
* description: Error code
* example: E_INTERNAL_SERVER_ERROR
* message:
* type: string
* description: Error message
* example: Invalid OIDC configuration
*/
const { getRemoteAddress } = require('../../../utils/remote-address');
const Errors = {

40
server/api/controllers/access-tokens/revoke-pending-token.js
View File

@@ -3,6 +3,46 @@
* Licensed under the Fair Use License: https://github.com/plankanban/planka/blob/master/LICENSE.md
*/
/**
* @swagger
* /api/access-tokens/revoke-pending-token:
* post:
* summary: Revoke pending token
* description: Revokes a pending authentication token and cancels the authentication flow.
* tags:
* - Access Tokens
* requestBody:
* required: true
* content:
* application/json:
* schema:
* type: object
* required:
* - pendingToken
* properties:
* pendingToken:
* type: string
* maxLength: 1024
* description: Pending token to revoke
* example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ4...
* responses:
* 200:
* description: Pending token revoked successfully
* content:
* application/json:
* schema:
* type: object
* properties:
* item:
* type: null
* description: No data returned
* example: null
* 400:
* $ref: '#/components/responses/ValidationError'
* 404:
* $ref: '#/components/responses/NotFound'
*/
const Errors = {
PENDING_TOKEN_NOT_FOUND: {
pendingTokenNotFound: 'Pending token not found',