-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: add swagger for REST API #2
base: develop
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,335 @@ | ||
openapi: 3.0.0 | ||
|
||
tags: | ||
- name: immutable | ||
- name: mutable | ||
|
||
info: | ||
title: Crasher REST API | ||
description: Current API describes UI interaction with Crasher | ||
version: 1.0.0 | ||
|
||
paths: | ||
/applications: | ||
get: | ||
summary: Get application names | ||
description: Method returns application names that have core dumps | ||
tags: | ||
- immutable | ||
responses: | ||
200: | ||
description: Ok | ||
content: | ||
application/json: | ||
schema: | ||
type: object | ||
properties: | ||
applications: | ||
type: array | ||
items: | ||
type: string | ||
description: name of the application | ||
required: | ||
- applications | ||
examples: | ||
applications: | ||
value: | ||
- "auth-service" | ||
- "web-scraper-service" | ||
- "seller-service" | ||
500: | ||
description: Server error | ||
|
||
/core_dumps: | ||
get: | ||
summary: Get core dump previews | ||
description: Method returns core dump previews with pagination | ||
parameters: | ||
- in: query | ||
name: minTimestamp | ||
description: min core dump creation time | ||
schema: | ||
type: integer | ||
- in: query | ||
name: maxTimestamp | ||
description: max core dump creation time | ||
schema: | ||
type: integer | ||
- in: query | ||
name: application | ||
description: application name | ||
schema: | ||
type: string | ||
- in: query | ||
name: offset | ||
description: core dumps offset for pagination page | ||
required: true | ||
schema: | ||
type: integer | ||
- in: query | ||
name: limit | ||
description: core dumps limit for pagination page | ||
required: true | ||
schema: | ||
type: integer | ||
tags: | ||
- immutable | ||
responses: | ||
200: | ||
description: Ok | ||
content: | ||
application/json: | ||
schema: | ||
type: object | ||
properties: | ||
pagination: | ||
type: object | ||
properties: | ||
totalSize: | ||
type: integer | ||
description: total size core dumps by this request | ||
prev: | ||
type: string | ||
description: url path for previous pagination page | ||
self: | ||
type: string | ||
description: url path for current pagination page | ||
next: | ||
type: string | ||
description: url path for next pagination page | ||
required: | ||
- totalSize | ||
- self | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. how does server tells a client that it was the last page? By |
||
coreDumps: | ||
type: array | ||
items: | ||
type: object | ||
properties: | ||
id: | ||
type: string | ||
description: core dump id | ||
status: | ||
type: number | ||
description: core dump status | ||
enum: | ||
- 0 | ||
- 1 | ||
- 2 | ||
- 3 | ||
timestamp: | ||
type: number | ||
description: core dump creation time | ||
appInfo: | ||
type: object | ||
properties: | ||
name: | ||
type: string | ||
description: name of the application | ||
version: | ||
type: string | ||
description: version of the application | ||
osInfo: | ||
type: object | ||
properties: | ||
name: | ||
type: string | ||
description: description of the operating system | ||
required: | ||
- id | ||
- status | ||
- timestamp | ||
required: | ||
- pagination | ||
- coreDumps | ||
examples: | ||
example: | ||
value: | ||
pagination: | ||
value: | ||
totalSize: 127 | ||
prev: "/core_dumps?minTimestamp={minTimestamp}&maxTimestamp={maxTimestamp}&application={application}&offset={start}&limit={limit}" | ||
self: "/core_dumps?minTimestamp={minTimestamp}&maxTimestamp={maxTimestamp}&application={application}&offset={start}&limit={limit}" | ||
next: "/core_dumps?minTimestamp={minTimestamp}&maxTimestamp={maxTimestamp}&application={application}&offset={start}&limit={limit}" | ||
coreDumps: | ||
- id: "507f1f77bcf86cd799439011" | ||
status: 1 | ||
timestamp: 1663355412 | ||
appInfo: | ||
value: | ||
name: "auth-service" | ||
version: "1.5.45" | ||
osInfo: | ||
value: | ||
name: "windows 10" | ||
400: | ||
description: Bad request | ||
500: | ||
description: Server error | ||
delete: | ||
summary: Delete all core dumps | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. maybe add some optional parameters, by application, by status and etc.? |
||
description: Method removes all core dumps | ||
tags: | ||
- mutable | ||
responses: | ||
200: | ||
description: Ok | ||
500: | ||
description: Server error | ||
|
||
/core_dump/{id}: | ||
get: | ||
summary: Get core dump by id | ||
description: Method returns all the information about core dump by id | ||
parameters: | ||
- name: id | ||
in: path | ||
required: true | ||
description: Core dump id | ||
schema: | ||
type : string | ||
tags: | ||
- immutable | ||
responses: | ||
200: | ||
description: Ok | ||
content: | ||
application/json: | ||
schema: | ||
type: object | ||
properties: | ||
coreDump: | ||
type: object | ||
properties: | ||
id: | ||
type: string | ||
description: core dump id | ||
data: | ||
type: string | ||
description: core dump data | ||
status: | ||
type: number | ||
description: core dump status | ||
enum: | ||
- 0 | ||
- 1 | ||
- 2 | ||
- 3 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. it seems to me that it can be bad approach to make enums in rest api, i think it's better to use string representations of status. |
||
timestamp: | ||
type: number | ||
description: core dump creation time | ||
appInfo: | ||
type: object | ||
properties: | ||
name: | ||
type: string | ||
description: name of the application | ||
version: | ||
type: string | ||
description: version of the application | ||
language: | ||
type: string | ||
description: language of the application | ||
osInfo: | ||
type: object | ||
properties: | ||
name: | ||
type: string | ||
description: name of the operating system | ||
version: | ||
type: string | ||
description: version of the operating system | ||
architecture: | ||
type: string | ||
description: architecture of the operating system | ||
required: | ||
- id | ||
- data | ||
- status | ||
- timestamp | ||
required: | ||
- coreDump | ||
examples: | ||
example: | ||
value: | ||
coreDump: | ||
value: | ||
value: | ||
id: "507f1f77bcf86cd799439011" | ||
data: "goroutine 1 [running]:main.Example(0x2080c3f50, 0x2, 0x4, 0x425c0, 0x5, 0xa) /Users/bill/Spaces/Go/Projects/src/github.com/goinaction/code/temp/main.go:9 +0x64 main.main() /Users/bill/Spaces/Go/Projects/src/github.com/goinaction/code/temp/main.go:5 +0x85" | ||
status: 1 | ||
timestamp: 1663355412 | ||
appInfo: | ||
value: | ||
name: "auth-service" | ||
version: "1.5.45" | ||
language: "go" | ||
osInfo: | ||
value: | ||
name: "windows 10" | ||
version: "21H2" | ||
architecture: "x64" | ||
404: | ||
description: Not found | ||
500: | ||
description: Server error | ||
put: | ||
summary: Update core dump by id | ||
description: Method updates core dump by id | ||
parameters: | ||
- name: id | ||
in: path | ||
required: true | ||
description: Core dump id | ||
schema: | ||
type : string | ||
requestBody: | ||
required: true | ||
content: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. PUT method. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we intend to allow updating only status, no? |
||
application/json: | ||
schema: | ||
type: object | ||
properties: | ||
status: | ||
type: integer | ||
description: core dump status | ||
enum: | ||
- 0 | ||
- 1 | ||
- 2 | ||
- 3 | ||
required: | ||
- status | ||
examples: | ||
example: | ||
value: | ||
status: 2 | ||
tags: | ||
- mutable | ||
responses: | ||
200: | ||
description: Ok | ||
400: | ||
description: Bad request | ||
404: | ||
description: Not found | ||
500: | ||
description: Server error | ||
delete: | ||
summary: Delete core dump by id | ||
description: Method removes core dump by id | ||
parameters: | ||
- name: id | ||
in: path | ||
required: true | ||
description: Core dump id | ||
schema: | ||
type : string | ||
tags: | ||
- mutable | ||
responses: | ||
200: | ||
description: Ok | ||
404: | ||
description: Not found | ||
500: | ||
description: Server error |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we consider "Crasher" as the whole system that consists of UI, language libraries and server? If so let's say with Crasher Server.