From e78fb556a3e0b39c149483f9b99f64939ebcc233 Mon Sep 17 00:00:00 2001 From: b1ek Date: Thu, 29 Aug 2024 14:53:33 +1000 Subject: [PATCH] feat: openapi --- public/openapi.yml | 318 ++++++++++++++++++++++++++++++ resources/views/welcome.blade.php | 170 +--------------- 2 files changed, 328 insertions(+), 160 deletions(-) create mode 100644 public/openapi.yml diff --git a/public/openapi.yml b/public/openapi.yml new file mode 100644 index 0000000..0f544ae --- /dev/null +++ b/public/openapi.yml @@ -0,0 +1,318 @@ +info: + title: Parameters API + version: '1.0' +openapi: '3.0.1' +tags: + - name: Users + - name: Private routes + description: Accessible only to authenticated users +paths: + /api/users/reg: + put: + description: Create new user + tags: + - Users + requestBody: + content: + application/json: + schema: + type: object + properties: + user: + $ref: '#/components/schemas/User' + password: + type: string + example: 'strong_password123' + responses: + 200: + description: |- + User registered successfully. + + There is no response body + 400: + description: |- + There is an issue with your request. + + Response string is an enum: + + | key | val | + | --- | --- | + | `bad_password` | the password is too weak. it must score at least 3 by zxcvbn | + | `bad_email` | email doesn't match the email regex | + | `email_taken` | the email is already registered. user is expected to either log in or reset password | + + This error also might be sent by laravel if your body is corrupted + content: + application/json: + schema: + type: string + example: 'bad_password' + /api/users/login: + post: + tags: + - Users + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + example: 'jdoe@example.com' + password: + type: string + example: 'strong_password123' + responses: + 200: + description: |- + User authenticated successfully. + + There is no response body. Session will be set via laravel session. + 400: + description: |- + Email or password are invalid. + + Response string is an enum: + + | key | val | + | --- | --- | + | `bad_email` | email is not a valid email | + | `bad_password` | authentication unsuccessful; this means that there is either no user with this email, or password doesn't match | + + This error also might be sent by laravel if your body is corrupted + /api/users/reset: + post: + tags: + - Users + requestBody: + content: + application/json: + schema: + type: object + properties: + email: + type: string + example: 'jdoe@example.com' + responses: + 200: + description: |- + A reset password link is sent to the email, if such an account exists. + + If no mailer is set and it is debug mode, link will be available in `X-Reset-Link` + 400: + description: |- + Invalid email + + This error also might be sent by laravel if your body is corrupted + + /api/users/private/list: + get: + tags: + - Private routes + security: + - jwt: [] + responses: + 200: + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' + /api/users/private/get/{id}: + get: + parameters: + - name: id + in: path + required: true + schema: + type: string + tags: + - Private routes + security: + - jwt: [] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/User' + 400: + description: Invalid ID + 404: + description: User not found + /api/users/private/edit/{id}: + put: + parameters: + - name: id + in: path + required: true + schema: + type: string + tags: + - Private routes + security: + - jwt: [] + responses: + 200: + description: OK + requestBody: + description: |- + All fields of `user` are required. The whole record will be updated with exactly what you provide here. It is assumed that you already have all information about the user beforehand + + `new_pass` is optional, only if you want to update the password. + + Note: updating password will revoke all current sessions of the user + content: + application/json: + schema: + type: object + properties: + user: + $ref: '#/components/schemas/User' + new_pass: + type: string + example: 'very_strong_password123456' + /api/users/private/trash/group: + put: + summary: Add user(s) to trash + tags: + - Private routes + security: + - jwt: [] + parameters: + - name: ids + in: query + required: true + schema: + type: string + example: 'comma,separated,values' + responses: + 200: + description: OK + 404: + description: One or more users not found + content: + application/json: + schema: + type: array + items: + type: string + example: 'userid' + delete: + summary: Remove user(s) from trash + tags: + - Private routes + security: + - jwt: [] + parameters: + - name: ids + in: query + required: true + schema: + type: string + example: 'comma,separated,values' + responses: + 200: + description: |- + OK + + Note: will return OK even if some users were not in trash in the first place + 404: + description: One or more users not found + content: + application/json: + schema: + type: array + items: + type: string + example: 'userid' + /api/users/private/trash/clean: + delete: + summary: Delete user(s) for good from trash + tags: + - Private routes + security: + - jwt: [] + parameters: + - name: ids + in: query + required: true + schema: + type: string + example: 'comma,separated,values' + responses: + 200: + description: OK + 404: + description: The following user IDs were not in trash in the first place + content: + application/json: + schema: + type: array + items: + type: string + /api/users/private/trash/list: + get: + summary: List users in trash + tags: + - Private routes + security: + - jwt: [] + responses: + 200: + description: OK + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' +components: + schemas: + User: + type: object + properties: + id: + type: string + example: 'uuid-like' + last_name: + type: string + example: 'doe' + name: + type: string + example: 'john' + middle_name: + type: string + example: 'john' + email: + type: string + example: 'jdoe@example.com' + phone: + type: string + example: '+000000000' + deleted_at: + type: string + example: null + created_at: + type: string + example: null + updated_at: + type: string + example: null + Password: + type: object + properties: + user_id: + type: number + example: 1 + password: + type: string + example: 'argon2-hash-here' + securitySchemes: + jwt: + type: http + scheme: bearer diff --git a/resources/views/welcome.blade.php b/resources/views/welcome.blade.php index a9898e3..5257d5a 100644 --- a/resources/views/welcome.blade.php +++ b/resources/views/welcome.blade.php @@ -4,169 +4,19 @@ - Laravel + OpenAPI Spec - - - - - - + -
- -
-
-
-
- -
- @if (Route::has('login')) - - @endif -
- -
-
- -
- Laravel documentation screenshot - -
-
- -
-
-
- -
- -
-

Documentation

- -

- Laravel has wonderful documentation covering every aspect of the framework. Whether you are a newcomer or have prior experience with Laravel, we recommend reading our documentation from beginning to end. -

-
-
- - -
- - - -
- -
- -
-

Laracasts

- -

- Laracasts offers thousands of video tutorials on Laravel, PHP, and JavaScript development. Check them out, see for yourself, and massively level up your development skills in the process. -

-
- - - - - -
- -
- -
-

Laravel News

- -

- Laravel News is a community driven portal and newsletter aggregating all of the latest and most important news in the Laravel ecosystem, including new package releases and tutorials. -

-
- - - - -
-
- - - - - -
- -
-

Vibrant Ecosystem

- -

- Laravel's robust library of first-party tools and libraries, such as Forge, Vapor, Nova, Envoyer, and Herd help you take your projects to the next level. Pair them with powerful open source libraries like Cashier, Dusk, Echo, Horizon, Sanctum, Telescope, and more. -

-
-
-
-
- -
- Laravel v{{ Illuminate\Foundation\Application::VERSION }} (PHP v{{ PHP_VERSION }}) -
-
-
-
+ +