-
-
Notifications
You must be signed in to change notification settings - Fork 152
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Centralization of some OpenAPI docs (#7386)
Centralization and expansion of (some) OpenAPI docs
- Loading branch information
1 parent
6f76558
commit fa6dd53
Showing
9 changed files
with
276 additions
and
292 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -21,8 +21,10 @@ This module doesn't export any methods. | |
use strict; | ||
use warnings; | ||
|
||
use LedgerSMB::Router appname => 'erp/api'; | ||
|
||
|
||
set api_schema => openapi_schema(\*DATA); | ||
|
||
|
||
=head1 LICENSE AND COPYRIGHT | ||
|
@@ -40,24 +42,98 @@ your software. | |
|
||
|
||
__DATA__ | ||
openapi: 3.0.0 | ||
openapi: 3.0.3 | ||
info: | ||
title: LedgerSMB API | ||
version: 0.0.1 | ||
contact: | ||
name: "LedgerSMB API Support" | ||
url: "https://github.com/ledgersmb/LedgerSMB/issues" | ||
description: LedgerSMB API | ||
email: [email protected] | ||
description: | | ||
LedgerSMB comes with a web service API. The version number assigned follows | ||
the [rules of semantic versioning](https://semver.org/). The current major | ||
version is 0 (zero), meaning that it's not considered to have stabilized | ||
yet. The main reason is that not all functions have been ironed out yet: | ||
filtering, sorting and pagination are to be specified and implemented. | ||
The API is hosted on `erp/api/v0`, on the same root as `login.pl`. That is | ||
to say that if LedgerSMB's login screen is hosted at | ||
`https://example.org/login.pl` then the API can be found at | ||
`https://example.org/erp/api/v0`. All paths mentioned in this document will | ||
be appended to that. E.g. the items in the menu for the authenticated user | ||
can be accessed through `https://example.org/erp/api/v0/menu-nodes`. | ||
license: | ||
name: GPL-2.0-or-later | ||
url: https://spdx.org/licenses/GPL-2.0-or-later.html | ||
servers: | ||
servers: | ||
- url: 'http://lsmb/erp/api/v0' | ||
security: | ||
- cookieAuth: [] | ||
components: | ||
headers: | ||
ETag: | ||
description: | | ||
The API uses the ETag parameter to prevent different clients modifying | ||
the same resource around the same time from overwriting each other's | ||
data: the later updates will be rejected based on verification of this | ||
parameter. | ||
Clients need to retain the ETag returned on a request when they might | ||
want to update the values later. | ||
required: true | ||
schema: | ||
type: string | ||
parameters: | ||
if-match: | ||
name: If-Match | ||
in: header | ||
description: | | ||
Clients need to provide the If-Match parameter on update operations | ||
(PUT and PATCH) with the ETag obtained in the request from which | ||
data are being updated. Requests missing this header will be | ||
rejected with HTTP response code 428. Requests trying to update | ||
outdated content will be rejected with HTTP response code 412. | ||
required: true | ||
schema: | ||
type: string | ||
responses: | ||
304: | ||
description: Not modified | ||
400: | ||
description: Bad request | ||
401: | ||
description: Unauthorized | ||
403: | ||
description: Forbidden | ||
404: | ||
description: Not Found | ||
412: | ||
description: Precondition failed (If-Match header) | ||
413: | ||
description: Payload too large | ||
428: | ||
description: Precondition required | ||
securitySchemes: | ||
cookieAuth: | ||
type: apiKey | ||
in: cookie | ||
name: LedgerSMB-1.10 | ||
security: | ||
- cookieAuth: [] | ||
description: | | ||
The authenticating cookie can be obtained by sending a `POST` request | ||
to `login.pl?action=authenticate&company=<url-encoded-company` with a | ||
JSON object in the body of the request, containing these three fields | ||
* company | ||
* username | ||
* password | ||
as if they had been entered on the login page in the browser. Please | ||
note that the request `Content-Type` must be set to `application/json` | ||
and that an `X-Requested-With` header is expected with the value | ||
`XMLHttpRequest`. | ||
**Note**: the cookie value is updated on each response; the next | ||
request *must* be executed with the new cookie value. | ||
**Note 2**: the validity of the cookie is as long the user's timeout | ||
when logged into the application (default: 90 minutes). |
Oops, something went wrong.