first commit
This commit is contained in:
meninjar
@@ -0,0 +1,17 @@
|
||||
# Person Service API Documentation
|
||||
|
||||
## Overview
|
||||
This document provides comprehensive documentation for the Person Service API, including REST and gRPC endpoints.
|
||||
|
||||
## Table of Contents
|
||||
1. [REST API Endpoints](#rest-api-endpoints)
|
||||
2. [gRPC API Endpoints](#grpc-api-endpoints)
|
||||
3. [Request/Response Examples](#requestresponse-examples)
|
||||
4. [Error Handling](#error-handling)
|
||||
5. [Authentication](#authentication)
|
||||
6. [Rate Limiting](#rate-limiting)
|
||||
|
||||
## REST API Endpoints
|
||||
|
||||
### Base URL
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
# gRPC Documentation
|
||||
|
||||
TODO: Add documentation for gRPC services.
|
||||
@@ -0,0 +1,36 @@
|
||||
# gRPC API Endpoints - Person Service
|
||||
# Generated on: $(date)
|
||||
# Handler: internal/infrastructure/transport/grpc/handlers/person_handler.go
|
||||
|
||||
## Service: PersonService
|
||||
|
||||
### 1. GetPerson
|
||||
- **Method**: GetPerson
|
||||
- **Request**: GetPersonRequest { id: int64 }
|
||||
- **Response**: GetPersonResponse { person: Person }
|
||||
- **Handler**: PersonHandler.GetPerson()
|
||||
|
||||
### 2. ListPersons
|
||||
- **Method**: ListPersons
|
||||
- **Request**: ListPersonsRequest { page: int32, page_size: int32 }
|
||||
- **Response**: ListPersonsResponse { persons: []Person, total: int64 }
|
||||
- **Handler**: PersonHandler.ListPersons()
|
||||
|
||||
### 3. CreatePerson
|
||||
- **Method**: CreatePerson
|
||||
- **Request**: CreatePersonRequest { data: CreatePersonRequest }
|
||||
- **Response**: GetPersonResponse { person: Person }
|
||||
- **Handler**: PersonHandler.CreatePerson()
|
||||
|
||||
### 4. UpdatePerson
|
||||
- **Method**: UpdatePerson
|
||||
- **Request**: UpdatePersonRequest { id: int64, data: CreatePersonRequest }
|
||||
- **Response**: GetPersonResponse { person: Person }
|
||||
- **Handler**: PersonHandler.UpdatePerson()
|
||||
|
||||
### 5. DeletePerson
|
||||
- **Method**: DeletePerson
|
||||
- **Request**: DeletePersonRequest { id: int64 }
|
||||
- **Response**: Empty {}
|
||||
- **Handler**: PersonHandler.DeletePerson()
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: Person Service API
|
||||
description: REST API for Person Management Service
|
||||
version: 1.0.0
|
||||
contact:
|
||||
name: API Support
|
||||
email: [email protected]
|
||||
servers:
|
||||
- url: http://localhost:8080/api/v1
|
||||
description: Development server
|
||||
paths:
|
||||
/persons:
|
||||
get:
|
||||
summary: Get list of persons
|
||||
description: Retrieve paginated list of persons
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
description: Page number
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 1
|
||||
- name: limit
|
||||
in: query
|
||||
description: Items per page
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
default: 10
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PaginatedPersonResponse'
|
||||
post:
|
||||
summary: Create new person
|
||||
description: Create a new person record
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreatePersonRequest'
|
||||
responses:
|
||||
'201':
|
||||
description: Person created successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PersonResponse'
|
||||
/persons/{id}:
|
||||
get:
|
||||
summary: Get person detail
|
||||
description: Retrieve detailed information about a specific person
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: Person ID
|
||||
schema:
|
||||
type: integer
|
||||
format: int64
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PersonResponse'
|
||||
'404':
|
||||
description: Person not found
|
||||
put:
|
||||
summary: Update person
|
||||
description: Update an existing person record
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: Person ID
|
||||
schema:
|
||||
type: integer
|
||||
format: int64
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreatePersonRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: Person updated successfully
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PersonResponse'
|
||||
'404':
|
||||
description: Person not found
|
||||
components:
|
||||
schemas:
|
||||
CreatePersonRequest:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
phone:
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
- email
|
||||
PersonResponse:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
format: int64
|
||||
name:
|
||||
type: string
|
||||
email:
|
||||
type: string
|
||||
phone:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
PaginatedPersonResponse:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/PersonResponse'
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
page:
|
||||
type: integer
|
||||
limit:
|
||||
type: integer
|
||||
total:
|
||||
type: integer
|
||||
total_pages:
|
||||
type: integer
|
||||
@@ -0,0 +1,39 @@
|
||||
# REST API Endpoints - Person Service
|
||||
# Generated on: $(date)
|
||||
# Handler: internal/infrastructure/transport/http/handlers/person_handler.go
|
||||
|
||||
## Base Path: /api/v1/persons
|
||||
|
||||
### 1. Get List of Persons (Pagination)
|
||||
- **Method**: GET
|
||||
- **Path**: /persons
|
||||
- **Query Parameters**:
|
||||
- page (int, optional): Page number (default: 1)
|
||||
- limit (int, optional): Items per page (default: 10)
|
||||
- **Response**: Paginated list of persons
|
||||
- **Handler**: PersonHandler.GetList()
|
||||
|
||||
### 2. Get Person Detail
|
||||
- **Method**: GET
|
||||
- **Path**: /persons/{id}
|
||||
- **Path Parameters**:
|
||||
- id (int64, required): Person ID
|
||||
- **Response**: Single person details
|
||||
- **Handler**: PersonHandler.GetDetail()
|
||||
|
||||
### 3. Create New Person
|
||||
- **Method**: POST
|
||||
- **Path**: /persons
|
||||
- **Request Body**: CreatePersonRequest JSON
|
||||
- **Response**: Created person details
|
||||
- **Handler**: PersonHandler.Create()
|
||||
|
||||
### 4. Update Person
|
||||
- **Method**: PUT
|
||||
- **Path**: /persons/{id}
|
||||
- **Path Parameters**:
|
||||
- id (int64, required): Person ID
|
||||
- **Request Body**: CreatePersonRequest JSON
|
||||
- **Response**: Updated person details
|
||||
- **Handler**: PersonHandler.Update()
|
||||
|
||||
Reference in New Issue
Block a user