Created
September 16, 2020 08:39
-
-
Save JohnRoux/d2e3963e29c040b3b503675ea95d89af to your computer and use it in GitHub Desktop.
Example Swagger doc using allOf for Object contents
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", | |
| "info": { | |
| "title": "Demo App", | |
| "contact": { | |
| "email": "support@demo.app" | |
| }, | |
| "version": "1.0.0" | |
| }, | |
| "paths": { | |
| "/api/auth/login": { | |
| "post": { | |
| "tags": [ | |
| "Authentication" | |
| ], | |
| "summary": "User Login", | |
| "description": "Provides an email and a password and expects a JWT token in return", | |
| "operationId": "auth_login", | |
| "requestBody": { | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "required": [ | |
| "email", | |
| "password" | |
| ], | |
| "properties": { | |
| "email": { | |
| "description": "Email address associated with the user", | |
| "type": "string", | |
| "example": "admin@saythanks.com" | |
| }, | |
| "password": { | |
| "description": "Password associated with the user", | |
| "type": "string", | |
| "example": "password" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| } | |
| } | |
| }, | |
| "responses": { | |
| "200": { | |
| "description": "JWT Token", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/JwtToken" | |
| } | |
| } | |
| } | |
| }, | |
| "401": { | |
| "description": "The credentials you have entered are incorrect.", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "properties": { | |
| "error": { | |
| "description": "Error Message", | |
| "type": "string" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| } | |
| } | |
| }, | |
| "422": { | |
| "description": "Invalid Request", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "properties": { | |
| "message": { | |
| "description": "Error Message", | |
| "type": "string" | |
| }, | |
| "errors": { | |
| "description": "Contains an array or errors per field", | |
| "type": "array", | |
| "items": {} | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/api/auth/logout": { | |
| "post": { | |
| "tags": [ | |
| "Authentication" | |
| ], | |
| "summary": "User Logout", | |
| "description": "Log out the current user", | |
| "operationId": "auth_logout", | |
| "responses": { | |
| "200": { | |
| "description": "Successfully Logged out", | |
| "content": { | |
| "application/json": { | |
| "schema": {} | |
| } | |
| } | |
| }, | |
| "401": { | |
| "description": "Unauthorized", | |
| "content": { | |
| "application/json": { | |
| "schema": {} | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiAuth": [] | |
| } | |
| ] | |
| } | |
| }, | |
| "/api/auth/refresh": { | |
| "post": { | |
| "tags": [ | |
| "Authentication" | |
| ], | |
| "summary": "Token Refresh", | |
| "description": "Get a new token for the logged in user", | |
| "operationId": "auth_refresh", | |
| "responses": { | |
| "200": { | |
| "description": "JWT Token", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/JwtToken" | |
| } | |
| } | |
| } | |
| }, | |
| "401": { | |
| "description": "Unauthorized", | |
| "content": { | |
| "application/json": { | |
| "schema": {} | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiAuth": [] | |
| } | |
| ] | |
| } | |
| }, | |
| "/api/auth/me": { | |
| "get": { | |
| "tags": [ | |
| "Authentication" | |
| ], | |
| "summary": "Get the logged in user", | |
| "description": "Returns the user model logged in", | |
| "operationId": "auth_me", | |
| "parameters": [ | |
| { | |
| "$ref": "#/components/parameters/UserIncludes" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "User Model", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/User" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiAuth": [] | |
| } | |
| ] | |
| } | |
| }, | |
| "/api/user": { | |
| "get": { | |
| "tags": [ | |
| "User" | |
| ], | |
| "summary": "Get list of all users", | |
| "description": "Returns list of users", | |
| "operationId": "user_index", | |
| "parameters": [ | |
| { | |
| "$ref": "#/components/parameters/UserIncludes" | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "User Collection", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/User" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiAuth": [] | |
| } | |
| ] | |
| } | |
| }, | |
| "/api/user/{user_id}": { | |
| "get": { | |
| "tags": [ | |
| "User" | |
| ], | |
| "summary": "Get details of specific user", | |
| "description": "Returns data from a user", | |
| "operationId": "user_show", | |
| "parameters": [ | |
| { | |
| "name": "user_id", | |
| "in": "path", | |
| "description": "The Id of the user to return", | |
| "required": true, | |
| "schema": { | |
| "type": "integer" | |
| }, | |
| "example": 1 | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "User Item", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/UserCollection" | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "apiAuth": [] | |
| } | |
| ] | |
| } | |
| } | |
| }, | |
| "components": { | |
| "schemas": { | |
| "Pagination": { | |
| "title": "Pagination Object", | |
| "required": [ | |
| "total", | |
| "count", | |
| "per_page", | |
| "current_page", | |
| "links" | |
| ], | |
| "properties": { | |
| "meta": { | |
| "properties": { | |
| "pagination": { | |
| "properties": { | |
| "total": { | |
| "type": "integer" | |
| }, | |
| "count": { | |
| "type": "integer" | |
| }, | |
| "per_page": { | |
| "type": "integer" | |
| }, | |
| "current_page": { | |
| "type": "integer" | |
| }, | |
| "links": { | |
| "type": "object" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| }, | |
| "type": "object" | |
| }, | |
| "Item": { | |
| "title": "Item Object", | |
| "required": [ | |
| "id", | |
| "model_name" | |
| ], | |
| "properties": { | |
| "id": { | |
| "type": "integer" | |
| }, | |
| "model_name": { | |
| "type": "string" | |
| } | |
| }, | |
| "type": "object" | |
| }, | |
| "ItemCollection": { | |
| "title": "Item Collection Object", | |
| "required": [ | |
| "data" | |
| ], | |
| "properties": { | |
| "data": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/components/schemas/Item" | |
| } | |
| } | |
| }, | |
| "type": "object" | |
| }, | |
| "JwtToken": { | |
| "title": "JWT Token", | |
| "type": "object", | |
| "allOf": [ | |
| { | |
| "properties": { | |
| "user_id": { | |
| "type": "integer" | |
| }, | |
| "access_token": { | |
| "type": "string" | |
| }, | |
| "token_type": { | |
| "type": "string" | |
| }, | |
| "expires_in": { | |
| "type": "integer" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| ] | |
| }, | |
| "User": { | |
| "title": "User", | |
| "required": [ | |
| "id", | |
| "model_name" | |
| ], | |
| "type": "object", | |
| "allOf": [ | |
| { | |
| "$ref": "#/components/schemas/Item" | |
| }, | |
| { | |
| "properties": { | |
| "name": { | |
| "type": "string" | |
| }, | |
| "email": { | |
| "type": "string" | |
| }, | |
| "type": { | |
| "type": "string" | |
| }, | |
| "created_at": { | |
| "type": "string" | |
| }, | |
| "updated_at": { | |
| "type": "string" | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| ] | |
| }, | |
| "UserCollection": { | |
| "title": "User Collection", | |
| "type": "object", | |
| "allOf": [ | |
| { | |
| "$ref": "#/components/schemas/ItemCollection" | |
| }, | |
| { | |
| "properties": { | |
| "data": { | |
| "type": "array", | |
| "items": { | |
| "$ref": "#/components/schemas/User" | |
| } | |
| } | |
| }, | |
| "type": "object" | |
| } | |
| ] | |
| } | |
| }, | |
| "responses": { | |
| "ModelNotFound": { | |
| "description": "Unable to find model" | |
| }, | |
| "ErrorUnprocessableEntity": { | |
| "description": "Error with input, see error databags" | |
| } | |
| }, | |
| "parameters": { | |
| "CompanyIncludes": { | |
| "name": "include", | |
| "in": "query", | |
| "description": "Available relationships to include. Dot notation can be used to get nested relationships. Parse 'include={relationships}'", | |
| "schema": { | |
| "type": "string", | |
| "enum": [ | |
| "users" | |
| ] | |
| } | |
| }, | |
| "UserIncludes": { | |
| "name": "include", | |
| "in": "query", | |
| "description": "Available relationships to include. Dot notation can be used to get nested relationships. Parse 'include={relationships}'", | |
| "schema": { | |
| "type": "string", | |
| "enum": [ | |
| "company" | |
| ] | |
| } | |
| } | |
| }, | |
| "securitySchemes": { | |
| "apiAuth": { | |
| "type": "http", | |
| "description": "Login with email and password to get the authentication token", | |
| "name": "Token based Based", | |
| "in": "header", | |
| "bearerFormat": "JWT", | |
| "scheme": "bearer" | |
| } | |
| } | |
| }, | |
| "security": [ | |
| [] | |
| ] | |
| } |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment