feat: write template
This commit is contained in:
u80864958 committed
commit
a0a6d2cf84
98 files changed
+6609
No files matched your search
@@ -0,0 +1,630 @@
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/refs/heads/main/_archive_/schemas/v3.0/schema.yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: Example App Backend API
|
||||
version: "1.0.0"
|
||||
description: API for the Example App backend service.
|
||||
servers:
|
||||
- url: http://localhost:8080
|
||||
description: Local development server
|
||||
components:
|
||||
securitySchemes:
|
||||
cookieAuth:
|
||||
type: apiKey
|
||||
in: cookie
|
||||
name: auth
|
||||
description: Cookie-based authentication
|
||||
schemas:
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
description: Categorization of the error for programmatic handling.
|
||||
enum:
|
||||
- AUTHENTICATION_ERROR
|
||||
- AUTHORIZATION_ERROR
|
||||
- VALIDATION_ERROR
|
||||
- BAD_REQUEST_ERROR
|
||||
- NOT_FOUND_ERROR
|
||||
- SERVER_ERROR
|
||||
- UNKNOWN_ERROR
|
||||
example: AUTHENTICATION_ERROR
|
||||
key:
|
||||
description: A unique error code or identifier for specific error cases.
|
||||
type: string
|
||||
maxLength: 200
|
||||
example: example key
|
||||
message:
|
||||
type: string
|
||||
description: A human-readable message explaining the error.
|
||||
maxLength: 200
|
||||
example: example message
|
||||
details:
|
||||
type: object
|
||||
description: Additional context or metadata regarding the error (e.g.,
|
||||
specific field validation failures).
|
||||
x-go-type-skip-optional-pointer: true
|
||||
x-go-type: any
|
||||
additionalProperties: true
|
||||
example: {}
|
||||
required:
|
||||
- type
|
||||
- key
|
||||
- message
|
||||
description: Schema representing Error.
|
||||
example: {}
|
||||
UUID:
|
||||
type: string
|
||||
format: uuid
|
||||
x-go-type: uuid.UUID
|
||||
x-go-type-import:
|
||||
path: github.com/google/uuid
|
||||
name: uuid
|
||||
description: Schema representing UUID.
|
||||
example: example
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
description: Id of the user.
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/UUID"
|
||||
name:
|
||||
type: string
|
||||
description: Full name or display name of the user.
|
||||
example: "Example User"
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
description: Schema representing User.
|
||||
example: {}
|
||||
Claims:
|
||||
type: object
|
||||
properties:
|
||||
iss:
|
||||
type: string
|
||||
description: The issuer of the token.
|
||||
example: "example-app-backend"
|
||||
sub:
|
||||
description: The subject of the token (User ID).
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/UUID"
|
||||
iat:
|
||||
type: integer
|
||||
format: int64
|
||||
description: Issued At timestamp (Unix epoch).
|
||||
example: 1
|
||||
exp:
|
||||
type: integer
|
||||
format: int64
|
||||
description: Expiration timestamp (Unix epoch).
|
||||
example: 1
|
||||
required:
|
||||
- iss
|
||||
- sub
|
||||
- iat
|
||||
- exp
|
||||
|
||||
description: Schema representing Claims.
|
||||
example: {}
|
||||
Scan:
|
||||
type: object
|
||||
properties:
|
||||
isbn:
|
||||
type: string
|
||||
x-go-name: ISBN
|
||||
description: The International Standard Book Number.
|
||||
example: 978-3-16-148410-0
|
||||
required:
|
||||
- isbn
|
||||
|
||||
description: Schema representing Scan.
|
||||
example: {}
|
||||
Book:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
description: User facing id of the book.
|
||||
example: 1
|
||||
title:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 200
|
||||
description: The title of the book.
|
||||
example: example title
|
||||
authors:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 500
|
||||
description: A comma-separated list or string of book authors.
|
||||
example: example authors
|
||||
description:
|
||||
type: string
|
||||
minLength: 0
|
||||
maxLength: 2048
|
||||
description: A brief summary or synopsis of the book.
|
||||
example: example description
|
||||
lentBy:
|
||||
description: The user who has lent the book from the library.
|
||||
Undefined if the boook is not lent.
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/User"
|
||||
coverUrl:
|
||||
type: string
|
||||
format: url
|
||||
description: Link to the book's cover image.
|
||||
example: example cover_url
|
||||
required:
|
||||
- id
|
||||
- title
|
||||
- authors
|
||||
|
||||
description: Schema representing Book.
|
||||
example: {}
|
||||
BookDetails:
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/Book"
|
||||
- type: object
|
||||
properties:
|
||||
isbn:
|
||||
type: string
|
||||
x-go-name: ISBN
|
||||
minLength: 9
|
||||
maxLength: 20
|
||||
description: The ISBN of the book.
|
||||
example: example isbn
|
||||
publisher:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 200
|
||||
description: The entity that published the book.
|
||||
example: example publisher
|
||||
publishedAt:
|
||||
type: integer
|
||||
multipleOf: 1
|
||||
minimum: 0
|
||||
description: The publication year or timestamp.
|
||||
example: 1
|
||||
owner:
|
||||
description: The user who owns the bool. Undefined if the boook is
|
||||
public.
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/User"
|
||||
required:
|
||||
- isbn
|
||||
- publisher
|
||||
- publishedAt
|
||||
example: {}
|
||||
description: Schema representing BookDetails.
|
||||
BookRequest:
|
||||
type: object
|
||||
properties:
|
||||
title:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 200
|
||||
description: "The title of the book. (ctx: schema.BookRequest.properties.title)"
|
||||
example: example title
|
||||
authors:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 500
|
||||
description: "A comma-separated list or string of book authors. (ctx: schema.BookRequest.properties.authors)"
|
||||
example: example authors
|
||||
isbn:
|
||||
type: string
|
||||
x-go-name: ISBN
|
||||
minLength: 9
|
||||
maxLength: 20
|
||||
description: "The ISBN of the book. (ctx: schema.BookRequest.properties.isbn)"
|
||||
example: example isbn
|
||||
description:
|
||||
type: string
|
||||
minLength: 0
|
||||
maxLength: 2048
|
||||
description: "A brief summary or synopsis of the book. (ctx: schema.BookRequest.properties.description)"
|
||||
example: example description
|
||||
publisher:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 200
|
||||
description: "The entity that published the book. (ctx: schema.BookRequest.properties.publisher)"
|
||||
example: example publisher
|
||||
publishedAt:
|
||||
type: integer
|
||||
multipleOf: 1
|
||||
minimum: 0
|
||||
description: "The publication year or timestamp. (ctx: schema.BookRequest.properties.publishedAt)"
|
||||
example: 1
|
||||
public:
|
||||
type: boolean
|
||||
description: Whether the book is publicly owened or owned by the
|
||||
creating user.
|
||||
|
||||
example: true
|
||||
coverUrl:
|
||||
type: string
|
||||
format: url
|
||||
minLength: 0
|
||||
maxLength: 1024
|
||||
description: "Link to the book's cover image. (ctx: schema.BookRequest.properties.coverUrl)"
|
||||
example: example cover_url
|
||||
required:
|
||||
- title
|
||||
- authors
|
||||
- isbn
|
||||
- publisher
|
||||
- publishedAt
|
||||
- public
|
||||
|
||||
description: Schema representing BookRequest.
|
||||
example: {}
|
||||
Lending:
|
||||
type: object
|
||||
properties:
|
||||
user:
|
||||
description: The uuid of the user, who has lent the book
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/UUID"
|
||||
startedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: The ID of the user borrowing the book.
|
||||
example: example startedAt
|
||||
returnedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when the book was returned. Undefined if still
|
||||
out.
|
||||
example: example returnedAt
|
||||
required:
|
||||
- user
|
||||
- startedAt
|
||||
|
||||
description: Schema representing Lending.
|
||||
example: {}
|
||||
responses:
|
||||
Error400:
|
||||
description: Bad request
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
Error401:
|
||||
description: Unauthorized – missing or invalid auth cookie
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
Error403:
|
||||
description: Forbidden – this is probably not your book
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
Error404:
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
Error500:
|
||||
description: Server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
security:
|
||||
- cookieAuth: []
|
||||
|
||||
paths:
|
||||
/auth/login:
|
||||
post:
|
||||
summary: Login a user and receive an authentication cookie
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/UUID"
|
||||
description: Request body for POST /auth/login
|
||||
responses:
|
||||
"200":
|
||||
description: Successful login, authentication cookie set
|
||||
headers:
|
||||
Set-Cookie:
|
||||
schema:
|
||||
type: string
|
||||
example: auth=eyJhbGci...; Path=/; HttpOnly
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Claims"
|
||||
"400":
|
||||
description: Invalid request payload
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"401":
|
||||
description: Authentication failed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
security: []
|
||||
tags:
|
||||
- Auth
|
||||
operationId: post_auth_login
|
||||
description: Log in a user and receive an authentication cookie
|
||||
/auth/logout:
|
||||
post:
|
||||
summary: Logout the current user
|
||||
responses:
|
||||
"204":
|
||||
description: Successful logout and the cookie was removed
|
||||
headers:
|
||||
Set-Cookie:
|
||||
description: >
|
||||
Sets the auth cookie to an empty value and expires it immediately by
|
||||
setting Max-Age to 0. The token gets invalidated.
|
||||
schema:
|
||||
type: string
|
||||
example: auth=; Path=/; HttpOnly; Max-Age=0
|
||||
"401":
|
||||
description: Authentication failed
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Auth
|
||||
operationId: post_auth_logout
|
||||
description: Logout the current user
|
||||
/auth:
|
||||
get:
|
||||
summary: Retrieve the claims for the currently authenticated user
|
||||
responses:
|
||||
"200":
|
||||
description: Claims of the authenticated user
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Claims"
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
security: []
|
||||
tags:
|
||||
- Auth
|
||||
operationId: get_auth
|
||||
description: Retrieve the claims for the currently authenticated user
|
||||
|
||||
/auth/users:
|
||||
get:
|
||||
summary: List all users
|
||||
responses:
|
||||
"200":
|
||||
description: Array of user objects
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/User"
|
||||
example: []
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
security: []
|
||||
tags:
|
||||
- Auth
|
||||
operationId: get_auth_users
|
||||
description: List all users
|
||||
/books:
|
||||
get:
|
||||
summary: Get all books
|
||||
responses:
|
||||
"200":
|
||||
description: Array of books
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/Book"
|
||||
example: []
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
security: [] #no security needed
|
||||
|
||||
tags:
|
||||
- Books
|
||||
operationId: get_books
|
||||
description: Get all books
|
||||
post:
|
||||
summary: Register a new book
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BookRequest"
|
||||
|
||||
description: Request body for POST /books
|
||||
responses:
|
||||
"200":
|
||||
description: The new book
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Book"
|
||||
"400":
|
||||
$ref: "#/components/responses/Error400"
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Books
|
||||
operationId: post_books
|
||||
description: Register a new book
|
||||
/books/{bookID}:
|
||||
parameters:
|
||||
- name: bookID
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
|
||||
description: Parameter bookID for /books/{bookID}
|
||||
get:
|
||||
summary: Get the details of a book
|
||||
responses:
|
||||
"200":
|
||||
description: BookDetails
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BookDetails"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
security: [] #no security needed
|
||||
|
||||
tags:
|
||||
- Books
|
||||
operationId: get_books_bookID
|
||||
description: Get the details of a book
|
||||
put:
|
||||
summary: Update a book
|
||||
description: |
|
||||
The field lentBy will be ignored. If you want to lend a book, please use the corresponding route.
|
||||
The field owner will only be obeyed if you own the book and set it to null / undefined.
|
||||
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BookRequest"
|
||||
|
||||
description: Request body for PUT /books/{bookID}
|
||||
responses:
|
||||
"200":
|
||||
description: The new book
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BookDetails"
|
||||
"400":
|
||||
$ref: "#/components/responses/Error400"
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"403":
|
||||
$ref: "#/components/responses/Error403"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Books
|
||||
operationId: put_books_bookID
|
||||
delete:
|
||||
summary: Delete a book
|
||||
responses:
|
||||
"204":
|
||||
description: Book deleted successfully
|
||||
"403":
|
||||
$ref: "#/components/responses/Error403"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Books
|
||||
operationId: delete_books_bookID
|
||||
description: Delete a book
|
||||
/books/{bookID}/lending:
|
||||
parameters:
|
||||
- name: bookID
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
description: Parameter bookID for /books/{bookID}/lending
|
||||
post:
|
||||
summary: Lend a book
|
||||
responses:
|
||||
"204":
|
||||
description: The book is successfully lent
|
||||
"400":
|
||||
description: Bad request - The book is most likely already lent
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Lending
|
||||
operationId: post_books_bookID_lending
|
||||
description: Lend a book
|
||||
delete:
|
||||
summary: End a lending (return a book)
|
||||
responses:
|
||||
"204":
|
||||
description: The lending is successfully ended.
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"403":
|
||||
description: Forbidden – you do not have an open lending
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Lending
|
||||
operationId: delete_books_bookID_lending
|
||||
description: End a lending (return a book)
|
||||
/lookup:
|
||||
post:
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Scan"
|
||||
|
||||
description: Request body for POST /lookup
|
||||
responses:
|
||||
"200":
|
||||
description: Looked up book
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/BookRequest"
|
||||
"401":
|
||||
$ref: "#/components/responses/Error401"
|
||||
"404":
|
||||
$ref: "#/components/responses/Error404"
|
||||
"500":
|
||||
$ref: "#/components/responses/Error500"
|
||||
tags:
|
||||
- Lookup
|
||||
operationId: post_lookup
|
||||
description: POST operation for /lookup
|
||||
Reference in new issue
Block a user