mirror of
https://github.com/invoiceninja/invoiceninja.git
synced 2025-05-24 02:14:21 -04:00
Integrating OpenAPI documentation
This commit is contained in:
David Bomba
parent
95be70a7b5
commit
59abbd04f9
@ -39,6 +39,17 @@ class LoginController extends BaseController
|
||||
| to conveniently provide its functionality to your applications.
|
||||
|
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Tag(
|
||||
* name="login",
|
||||
* description="Authentication",
|
||||
* @OA\ExternalDocumentation(
|
||||
* description="Find out more",
|
||||
* url="http://docs.invoiceninja.com"
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
|
||||
use AuthenticatesUsers;
|
||||
use UserSessionAttributes;
|
||||
@ -86,6 +97,66 @@ class LoginController extends BaseController
|
||||
*
|
||||
* @return Response|User Process user login.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Post(
|
||||
* path="/api/v1/login",
|
||||
* operationId="postLogin",
|
||||
* tags={"login"},
|
||||
* summary="Attempts authentication",
|
||||
* description="Returns a CompanyUser object on success",
|
||||
* @OA\Parameter(ref="#/components/parameters/X-Api-Secret"),
|
||||
* @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/include_static"),
|
||||
* @OA\Parameter(ref="#/components/parameters/clear_cache"),
|
||||
* @OA\RequestBody(
|
||||
* description="User credentials",
|
||||
* required=true,
|
||||
* @OA\MediaType(
|
||||
* mediaType="application/json",
|
||||
* @OA\Schema(
|
||||
* type="object",
|
||||
* @OA\Property(
|
||||
* property="email",
|
||||
* description="The user email address",
|
||||
* type="string",
|
||||
* ),
|
||||
* @OA\Property(
|
||||
* property="password",
|
||||
* example="1234567",
|
||||
* description="The user password must meet minimum criteria ~ >6 characters",
|
||||
* type="string"
|
||||
* )
|
||||
* )
|
||||
* )
|
||||
* ),
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="The Company User response",
|
||||
* @OA\Header(header="X-API-TOKEN", ref="#/components/headers/X-API-TOKEN"),
|
||||
* @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/Company"),
|
||||
|
||||
* ),
|
||||
* @OA\Response(response=400, description="Bad request"),
|
||||
* security={
|
||||
* {"": {}}
|
||||
* }
|
||||
* )
|
||||
*
|
||||
* @OA\Response(
|
||||
* response=200,
|
||||
* description="Successful Authentication",
|
||||
* @OA\MediaType(
|
||||
* mediaType="application/json",
|
||||
* @OA\Schema(ref="#/components/schemas/Company"),
|
||||
* )
|
||||
* ),
|
||||
*/
|
||||
|
||||
public function apiLogin(Request $request)
|
||||
{
|
||||
$this->forced_includes = ['company_users'];
|
||||
|
||||
37
app/Http/Controllers/OpenAPI/CompanyUserSchema.php
Normal file
37
app/Http/Controllers/OpenAPI/CompanyUserSchema.php
Normal file
@ -0,0 +1,37 @@
|
||||
<?php
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="CompanyUser",
|
||||
* allOf={
|
||||
* @OA\Schema(
|
||||
* @OA\Property(property="permissions", type="string", example="[create_invoice]", description="The company user permissions"),
|
||||
* @OA\Property(property="settings", type="object", example="The local shop", description="The company name"),
|
||||
* @OA\Property(property="is_owner", type="boolean", example=true, description="Determines whether the user owns this company"),
|
||||
* @OA\Property(property="is_locked", type="boolean", example=true, description="Determines whether the users access to this company has been locked"),
|
||||
* @OA\Property(property="updated_at", type="int", example="1231232312321", description="The last time the record was modified"),
|
||||
* @OA\Property(property="deleted_at", type="int", example="1231232312321", description="Timestamp when the user was archived"),
|
||||
* )
|
||||
* }
|
||||
* )
|
||||
*/
|
||||
|
||||
|
||||
:
|
||||
type:
|
||||
properties:
|
||||
per_page:
|
||||
type: integer
|
||||
example: 25
|
||||
description: 'Used for the default number of items to be displayed in list views'
|
||||
|
||||
|
||||
|
||||
|
||||
company:
|
||||
$ref: '#/components/schemas/Company'
|
||||
user:
|
||||
$ref: '#/components/schemas/User'
|
||||
account:
|
||||
$ref: '#/components/schemas/Account'
|
||||
company_token:
|
||||
$ref: '#/components/schemas/CompanyToken'
|
||||
106
app/Http/Controllers/OpenAPI/Parameters.php
Normal file
106
app/Http/Controllers/OpenAPI/Parameters.php
Normal file
@ -0,0 +1,106 @@
|
||||
<?php
|
||||
/**
|
||||
* @OA\Parameter(
|
||||
* name="X-Api-Secret",
|
||||
* in="header",
|
||||
* description="The API secret as defined by the .env variable API_SECRET",
|
||||
* required=true,
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="password"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="X-Requested-With",
|
||||
* in="header",
|
||||
* description="Used to send the XMLHttpRequest header",
|
||||
* required=true,
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="XMLHttpRequest",
|
||||
* readOnly=true
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="X-Api-Token",
|
||||
* in="header",
|
||||
* description="The API token to be used for authentication",
|
||||
* required=true,
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="HcRvs0oCvYbY5g3RzgBZrSBOChCiq8u4AL0ieuFN5gn4wUV14t0clVhfPc5OX99q"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="include",
|
||||
* in="query",
|
||||
* description="Includes child relationships in the response, format is comma separated",
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="clients,invoices"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="include_static",
|
||||
* in="query",
|
||||
* description="Returns static variables",
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="include_static=true"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="clear_cache",
|
||||
* in="query",
|
||||
* description="Clears the static cache",
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="clear_cache=true"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="index",
|
||||
* in="query",
|
||||
* description="Replaces the default response index from data to a user specific string",
|
||||
* @OA\Schema(
|
||||
* type="string",
|
||||
* example="user"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Parameter(
|
||||
* name="",
|
||||
* in="query",
|
||||
* description="The API version",
|
||||
* @OA\Schema(
|
||||
* type="number",
|
||||
* example="user"
|
||||
* )
|
||||
* ),
|
||||
*
|
||||
* @OA\Header(
|
||||
* header="X-API-TOKEN",
|
||||
* description="The API version",
|
||||
* @OA\Schema( type="number" )
|
||||
* ),
|
||||
*
|
||||
* @OA\Header(
|
||||
* header="X-RateLimit-Remaining",
|
||||
* description="The number of requests left for the time window.",
|
||||
* @OA\Schema( type="integer" )
|
||||
* ),
|
||||
*
|
||||
* @OA\Header(
|
||||
* header="X-RateLimit-Limit",
|
||||
* description="The total number of requests in a given time window.",
|
||||
* @OA\Schema( type="integer" )
|
||||
* ),
|
||||
*/
|
||||
|
||||
|
||||
24
app/Http/Controllers/OpenAPI/Schema.php
Normal file
24
app/Http/Controllers/OpenAPI/Schema.php
Normal file
@ -0,0 +1,24 @@
|
||||
<?php
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="Company",
|
||||
* allOf={
|
||||
* @OA\Schema(
|
||||
* @OA\Property(property="id", type="string", example="WJxbojagwO", description="The company hash id"),
|
||||
* @OA\Property(property="name", type="string", example="The local shop", description="The company name"),
|
||||
* @OA\Property(property="logo", type="object", example="logo.png", description="The company logo - binary"),
|
||||
* @OA\Property(property="logo_url", type="string", example="http://example.com/logo.png", description="The company logo url"),
|
||||
* )
|
||||
* }
|
||||
* )
|
||||
*/
|
||||
|
||||
/**
|
||||
* @OA\Schema(
|
||||
* schema="product_id",
|
||||
* type="integer",
|
||||
* format="int64",
|
||||
* description="The unique identifier of a product in our catalog"
|
||||
* )
|
||||
*/
|
||||
26
app/Http/Controllers/OpenAPI/swagger-v3.php
Normal file
26
app/Http/Controllers/OpenAPI/swagger-v3.php
Normal file
@ -0,0 +1,26 @@
|
||||
<?php
|
||||
/**
|
||||
* @OA\OpenApi(
|
||||
* @OA\Info(
|
||||
* version="1.0.27",
|
||||
* title="Invoice Ninja",
|
||||
* description="Invoice Ninja. Open Source Invoicing lives here. ",
|
||||
* termsOfService="http://swagger.io/terms/",
|
||||
* @OA\Contact(
|
||||
* email="contact@invoiceninja.com"
|
||||
* ),
|
||||
* @OA\License(
|
||||
* name="Attribution Assurance License",
|
||||
* url="https://opensource.org/licenses/AAL"
|
||||
* )
|
||||
* ),
|
||||
* @OA\Server(
|
||||
* description="InvoiceNinja host",
|
||||
* url="https://virtserver.swaggerhub.com/InvoiceNinja/invoices/1.0.27"
|
||||
* ),
|
||||
* @OA\ExternalDocumentation(
|
||||
* description="http://docs.invoiceninja.com",
|
||||
* url="http://docs.invoiceninja.com"
|
||||
* )
|
||||
* )
|
||||
*/
|
||||
@ -49,6 +49,7 @@
|
||||
"require-dev": {
|
||||
"barryvdh/laravel-debugbar": "^3.2",
|
||||
"beyondcode/laravel-dump-server": "^1.0",
|
||||
"darkaonline/l5-swagger": "^6.0",
|
||||
"filp/whoops": "^2.0",
|
||||
"fzaninotto/faker": "^1.4",
|
||||
"laravel/dusk": "^5.0",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user