Created
August 26, 2022 22:52
-
-
Save nipunthathsara/49ace9ad9bc11217005c70560c54ba43 to your computer and use it in GitHub Desktop.
Genesis User Management ReST API contract - OAS3.0
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.0 | |
servers: | |
# Added by API Auto Mocking Plugin | |
- description: SwaggerHub API Auto Mocking | |
url: https://virtserver.swaggerhub.com/nipunthathsara/genesis-lms/1.0.0 | |
info: | |
description: Genesis User Management ReSTful APIs | |
version: "1.0.0" | |
title: Genesis User Management ReSTful APIs | |
contact: | |
email: nipunthathsara@gmail.com | |
license: | |
name: Apache 2.0 | |
url: 'http://www.apache.org/licenses/LICENSE-2.0.html' | |
tags: | |
- name: admins | |
description: Secured Admin-only calls | |
- name: developers | |
description: Operations available to regular developers | |
- name: users | |
description: Operations available to regular users | |
paths: | |
/users: | |
get: | |
tags: | |
- users | |
summary: get users | |
operationId: getUsers | |
description: | | |
Get a paginated list of users | |
parameters: | |
- in: query | |
name: filter | |
description: pass an optional search string to filter users | |
required: false | |
schema: | |
type: string | |
- in: query | |
name: offset | |
description: number of records to skip for pagination | |
schema: | |
type: integer | |
format: int32 | |
minimum: 0 | |
- in: query | |
name: limit | |
description: maximum number of records to return | |
schema: | |
type: integer | |
format: int32 | |
minimum: 1 | |
maximum: 50 | |
responses: | |
'200': | |
description: success | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/User' | |
'400': | |
description: bad request | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
post: | |
tags: | |
- users | |
summary: add user | |
operationId: addUser | |
description: | | |
Add user and optionally return the user | |
parameters: | |
- in: query | |
name: returnUser | |
description: include user in the response | |
required: false | |
schema: | |
type: boolean | |
requestBody: | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/CreateUser' | |
responses: | |
'201': | |
description: created | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/User' | |
'400': | |
description: bad request | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
'409': | |
description: user exists | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
/users/{userId}: | |
get: | |
tags: | |
- users | |
summary: get user by Id | |
operationId: getUserById | |
description: | | |
Get a specific user | |
parameters: | |
- in: path | |
name: userId | |
description: user id | |
required: true | |
schema: | |
type: string | |
responses: | |
'200': | |
description: success | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/User' | |
'404': | |
description: user not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
/roles: | |
get: | |
tags: | |
- users | |
summary: get roles | |
operationId: getRoles | |
description: | | |
Get a list of roles. | |
responses: | |
'200': | |
description: success | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Role' | |
'400': | |
description: bad request | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
post: | |
tags: | |
- admins | |
summary: add role | |
operationId: addRole | |
description: | | |
Create a new role | |
requestBody: | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/CreateRole' | |
responses: | |
'201': | |
description: created | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Role' | |
'400': | |
description: bad request | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
'409': | |
description: role exists | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
/roles/{roleId}: | |
get: | |
tags: | |
- users | |
summary: get role by Id | |
operationId: getRoleById | |
description: | | |
Get a specific role | |
parameters: | |
- in: path | |
name: roleId | |
description: role id | |
required: true | |
schema: | |
type: string | |
responses: | |
'200': | |
description: success | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Role' | |
'404': | |
description: role not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
/roles/{roleId}/users: | |
get: | |
tags: | |
- users | |
summary: get users of a role | |
operationId: getUsersOfRoleById | |
description: | | |
Get a list of users assigned to a specific role | |
parameters: | |
- in: path | |
name: roleId | |
description: role id | |
required: true | |
schema: | |
type: string | |
responses: | |
'200': | |
description: success | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/SimpleUser' | |
'404': | |
description: role not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
post: | |
tags: | |
- admins | |
summary: assign users to a role | |
operationId: assignUsersToRoleById | |
description: | | |
Assign list of users to a specific role | |
parameters: | |
- in: path | |
name: roleId | |
description: role id | |
required: true | |
schema: | |
type: string | |
requestBody: | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
type: string | |
format: uuid | |
example: d290f1ee-6c54-4b01-90e6-d701748f0851 | |
responses: | |
'204': | |
description: success | |
'400': | |
description: bad request | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
'404': | |
description: role not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
components: | |
schemas: | |
User: | |
type: object | |
required: | |
- id | |
- name | |
- dateOfBirth | |
properties: | |
id: | |
type: string | |
format: uuid | |
example: d290f1ee-6c54-4b01-90e6-d701748f0851 | |
name: | |
type: string | |
example: John Doe | |
email: | |
type: string | |
example: johndoe@genesis.com | |
dateOfBirth: | |
type: string | |
format: date | |
example: 2016-08-29 | |
SimpleUser: | |
type: object | |
properties: | |
id: | |
type: string | |
format: uuid | |
example: d290f1ee-6c54-4b01-90e6-d701748f0851 | |
name: | |
type: string | |
example: John Doe | |
CreateUser: | |
type: object | |
required: | |
- name | |
- dateOfBirth | |
- password | |
properties: | |
name: | |
type: string | |
example: John Doe | |
password: | |
type: string | |
example: vre%31H$23g | |
email: | |
type: string | |
example: johndoe@genesis.com | |
dateOfBirth: | |
type: string | |
format: date | |
example: 2016-08-29 | |
Role: | |
type: object | |
required: | |
- id | |
- name | |
properties: | |
id: | |
type: string | |
format: uuid | |
example: a290f1ee-6c54-4b01-90e6-d701748f0859 | |
name: | |
type: string | |
example: Manager | |
users: | |
type: array | |
items: | |
$ref: '#/components/schemas/SimpleUser' | |
CreateRole: | |
type: object | |
required: | |
- name | |
properties: | |
name: | |
type: string | |
example: Manager | |
Error: | |
type: object | |
required: | |
- name | |
properties: | |
correlationId: | |
type: string | |
format: uuid | |
example: a290f1ee-6c54-4b01-90e6-d701748f0859 | |
code: | |
type: string | |
example: GEN-10231 | |
message: | |
type: string | |
example: Some error message here |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment