Cutlery/invoiceninja
1
0
Fork 0
mirror of https://github.com/invoiceninja/invoiceninja.git synced 2025-06-23 20:00:33 -04:00
Code Issues Packages Projects Releases Wiki Activity

Completing OpenAPI documentation for clients

Browse Source
This commit is contained in:
David Bomba 2023-04-29 23:47:09 +10:00
parent c241a1e8fa
commit 4e8d1a58f2
6 changed files with 538 additions and 558 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

447
app/Http/Controllers/ClientController.php
View File

@ -68,39 +68,10 @@ class ClientController extends BaseController
} }
/** /**
* @OA\Get( *
* path="/api/v1/clients",
* operationId="getClients",
* tags={"clients"},
* summary="Gets a list of clients",
* description="Lists clients, search and filters allow fine grained lists to be generated.
* Query parameters can be added to performed more fine grained filtering of the clients, these are handled by the ClientFilters class which defines the methods available",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(ref="#/components/parameters/index"),
* @OA\Response(
* response=200,
* description="A list of clients",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
* @param ClientFilters $filters * @param ClientFilters $filters
* @return Response|mixed * @return Response
*
*/ */
public function index(ClientFilters $filters) public function index(ClientFilters $filters)
{ {
@ -118,47 +89,6 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
* @OA\Get(
* path="/api/v1/clients/{id}",
* operationId="showClient",
* tags={"clients"},
* summary="Shows a client",
* description="Displays a client by id",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the cl.ient object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function show(ShowClientRequest $request, Client $client) public function show(ShowClientRequest $request, Client $client)
{ {
@ -172,47 +102,6 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
* @OA\Get(
* path="/api/v1/clients/{id}/edit",
* operationId="editClient",
* tags={"clients"},
* summary="Shows a client for editting",
* description="Displays a client by id",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function edit(EditClientRequest $request, Client $client) public function edit(EditClientRequest $request, Client $client)
{ {
@ -226,48 +115,6 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
*
* @OA\Put(
* path="/api/v1/clients/{id}",
* operationId="updateClient",
* tags={"clients"},
* summary="Updates a client",
* description="Handles the updating of a client by id",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function update(UpdateClientRequest $request, Client $client) public function update(UpdateClientRequest $request, Client $client)
{ {
@ -290,37 +137,6 @@ class ClientController extends BaseController
* @param CreateClientRequest $request * @param CreateClientRequest $request
* @return Response * @return Response
* *
*
*
* @OA\Get(
* path="/api/v1/clients/create",
* operationId="getClientsCreate",
* tags={"clients"},
* summary="Gets a new blank client object",
* description="Returns a blank object with default values",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Response(
* response=200,
* description="A blank client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function create(CreateClientRequest $request) public function create(CreateClientRequest $request)
{ {
@ -335,37 +151,6 @@ class ClientController extends BaseController
* @param StoreClientRequest $request * @param StoreClientRequest $request
* @return Response * @return Response
* *
*
*
* @OA\Post(
* path="/api/v1/clients",
* operationId="storeClient",
* tags={"clients"},
* summary="Adds a client",
* description="Adds an client to a company",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Response(
* response=200,
* description="Returns the saved client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function store(StoreClientRequest $request) public function store(StoreClientRequest $request)
{ {
@ -392,47 +177,7 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
* @throws \Exception * @throws \Exception
* @OA\Delete(
* path="/api/v1/clients/{id}",
* operationId="deleteClient",
* tags={"clients"},
* summary="Deletes a client",
* description="Handles the deletion of a client by id",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns a HTTP status",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function destroy(DestroyClientRequest $request, Client $client) public function destroy(DestroyClientRequest $request, Client $client)
{ {
@ -446,61 +191,20 @@ class ClientController extends BaseController
* *
* @return Response * @return Response
* *
*
* @OA\Post(
* path="/api/v1/clients/bulk",
* operationId="bulkClients",
* tags={"clients"},
* summary="Performs bulk actions on an array of clients",
* description="",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/index"),
* @OA\RequestBody(
* description="User credentials",
* required=true,
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* type="array",
* @OA\Items(
* type="integer",
* description="Array of hashed IDs to be bulk 'actioned",
* example="[0,1,2,3]",
* ),
* )
* )
* ),
* @OA\Response(
* response=200,
* description="The Client User response",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function bulk(BulkClientRequest $request) public function bulk(BulkClientRequest $request)
{ {
$action = $request->action; $action = $request->action;
/** @var \App\Models\User $user */
$user = auth()->user();
$clients = Client::withTrashed() $clients = Client::withTrashed()
->company() ->company()
->whereIn('id', $request->ids) ->whereIn('id', $request->ids)
->cursor() ->cursor()
->each(function ($client) use ($action) { ->each(function ($client) use ($action, $user) {
if (auth()->user()->can('edit', $client)) { if ($user->can('edit', $client)) {
$this->client_repo->{$action}($client); $this->client_repo->{$action}($client);
} }
}); });
@ -515,48 +219,6 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
*
* @OA\Put(
* path="/api/v1/clients/{id}/upload",
* operationId="uploadClient",
* tags={"clients"},
* summary="Uploads a document to a client",
* description="Handles the uploading of a document to a client",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit"),
* @OA\JsonContent(ref="#/components/schemas/Client"),
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function upload(UploadClientRequest $request, Client $client) public function upload(UploadClientRequest $request, Client $client)
{ {
@ -578,47 +240,6 @@ class ClientController extends BaseController
* @param Client $client * @param Client $client
* @return Response * @return Response
* *
*
*
* @OA\Post(
* path="/api/v1/clients/{id}/purge",
* operationId="purgeClient",
* tags={"clients"},
* summary="Purges a client from the system",
* description="Handles purging a client",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit")
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function purge(PurgeClientRequest $request, Client $client) public function purge(PurgeClientRequest $request, Client $client)
{ {
@ -647,58 +268,6 @@ class ClientController extends BaseController
* @param string $mergeable_client * @param string $mergeable_client
* @return Response * @return Response
* *
*
*
* @OA\Post(
* path="/api/v1/clients/{id}/{mergeable_client_hashed_id}/merge",
* operationId="mergeClient",
* tags={"clients"},
* summary="Merges two clients",
* description="Handles merging 2 clients",
* @OA\Parameter(ref="#/components/parameters/X-API-TOKEN"),
* @OA\Parameter(ref="#/components/parameters/X-Requested-With"),
* @OA\Parameter(ref="#/components/parameters/include"),
* @OA\Parameter(
* name="id",
* in="path",
* description="The Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Parameter(
* name="mergeable_client_hashed_id",
* in="path",
* description="The Mergeable Client Hashed ID",
* example="D2J234DFA",
* required=true,
* @OA\Schema(
* type="string",
* format="string",
* ),
* ),
* @OA\Response(
* response=200,
* description="Returns the client object",
* @OA\Header(header="X-MINIMUM-CLIENT-VERSION", ref="#/components/headers/X-MINIMUM-CLIENT-VERSION"),
* @OA\Header(header="X-RateLimit-Remaining", ref="#/components/headers/X-RateLimit-Remaining"),
* @OA\Header(header="X-RateLimit-Limit", ref="#/components/headers/X-RateLimit-Limit")
* ),
* @OA\Response(
* response=422,
* description="Validation error",
* @OA\JsonContent(ref="#/components/schemas/ValidationError"),
*
* ),
* @OA\Response(
* response="default",
* description="Unexpected Error",
* @OA\JsonContent(ref="#/components/schemas/Error"),
* ),
* )
*/ */
public function merge(PurgeClientRequest $request, Client $client, string $mergeable_client) public function merge(PurgeClientRequest $request, Client $client, string $mergeable_client)

607
openapi/api-docs.yaml
View File

File diff suppressed because it is too large Load Diff

2
openapi/components/parameters.yaml
View File

@ -28,7 +28,7 @@
name: X-API-PASSWORD name: X-API-PASSWORD
in: header in: header
description: 'The login password when challenged on certain protected routes' description: 'The login password when challenged on certain protected routes'
required: false required: true
schema: schema:
type: string type: string
example: supersecretpassword example: supersecretpassword

15
openapi/components/schemas/generic_bulk_action.yaml Normal file
View File

@ -0,0 +1,15 @@
GenericBulkAction:
properties:
action:
type: string
example: archive
description: 'The action to perform ie. archive / restore / delete'
ids:
type: array
items:
format: string
type: string
example: 2J234DFA,D2J234DFA,D2J234DFA
description: string array of client hashed ids
type: object

21
openapi/paths/clients.yaml
View File

@ -133,7 +133,11 @@
tags: tags:
- clients - clients
summary: 'Create client' summary: 'Create client'
description: 'Adds a client to a company' description: |
Adds a client to a company
When creating (or updating) a client you must include the child contacts with all mutating requests. Client contacts cannot be modified in isolation.
operationId: storeClient operationId: storeClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -298,7 +302,7 @@
tags: tags:
- clients - clients
summary: 'Edit Client' summary: 'Edit Client'
description: 'Displays a client by id' description: 'Displays a client by id, essentially an alias of the show route'
operationId: editClient operationId: editClient
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
@ -383,19 +387,16 @@
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/index' - $ref: '#/components/parameters/index'
requestBody: requestBody:
description: 'User credentials' description: 'Bulk action array'
required: true required: true
content: content:
application/json: application/json:
schema: schema:
type: array $ref: '#/components/schemas/GenericBulkAction'
items:
description: 'Array of hashed IDs to be bulk ''actioned'
type: integer
example: '[0,1,2,3]'
responses: responses:
200: 200:
description: 'The Client User response' description: 'The Client listresponse'
headers: headers:
X-MINIMUM-CLIENT-VERSION: X-MINIMUM-CLIENT-VERSION:
$ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION' $ref: '#/components/headers/X-MINIMUM-CLIENT-VERSION'
@ -484,6 +485,7 @@
parameters: parameters:
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/X-API-PASSWORD'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- name: id - name: id
in: path in: path
@ -524,6 +526,7 @@
- $ref: '#/components/parameters/X-API-TOKEN' - $ref: '#/components/parameters/X-API-TOKEN'
- $ref: '#/components/parameters/X-Requested-With' - $ref: '#/components/parameters/X-Requested-With'
- $ref: '#/components/parameters/client_include' - $ref: '#/components/parameters/client_include'
- $ref: '#/components/parameters/X-API-PASSWORD'
- name: id - name: id
in: path in: path
description: 'The Client Hashed ID' description: 'The Client Hashed ID'

4
openapi/paths/credits.yaml
View File

@ -309,8 +309,8 @@
type: array type: array
items: items:
description: "Array of hashed IDs to be bulk 'actioned" description: "Array of hashed IDs to be bulk 'actioned"
type: integer type: string
example: "[0,1,2,3]" example: '[D2J234DFA,D2J234DFA,D2J234DFA]'
responses: responses:
200: 200:
description: "The Bulk Action response" description: "The Bulk Action response"