Browse Source

API draft for characters

Refs #27
feature/29
Martin Bober 4 months ago
parent
commit
93d5834bdf
  1. 433
      public/openapi.yaml
  2. 2
      swagger/Readme.md
  3. 2
      swagger/swagger-initializer.js

433
openapi.yaml → public/openapi.yaml

@ -3,10 +3,10 @@ info:
title: "Pen&PaperBox API"
version: 1.0.0
servers:
- url: http://localhost:3000/api
description: Local development sever
- url: https://penpaperbox.com/api
description: Production server
- url: http://localhost:3000/api
description: Local development sever
components:
securitySchemes:
bearer:
@ -14,6 +14,22 @@ components:
scheme: bearer
description: Bearer token that can be obtained via `/1.0/login`
schemas:
TimestampCreated:
type: object
properties:
created:
type: integer
description: Unix epoch seconds when the entity was first created
example: 1653112526
Timestamps:
allOf:
- $ref: '#/components/schemas/TimestampCreated'
- type: object
properties:
updated:
type: integer
description: Unix epoch seconds when the entity was last updated
example: 1653132603
Error:
type: object
properties:
@ -52,9 +68,11 @@ components:
filename:
type: string
description: Name of the file
example: 'image.jpg'
content_type:
type: string
description: Content type of the file
example: 'image/jpeg'
Image:
type: object
readOnly: true
@ -90,19 +108,40 @@ components:
$ref: '#/components/schemas/Image'
avatar_file:
$ref: '#/components/schemas/File'
email:
PlayerReference:
# Need to duplicate this because of this https://stackoverflow.com/a/51402417
readOnly: true
type: object
properties:
id:
type: integer
description: ID of the player
example: 23
readOnly: true
name:
type: string
example: bob@example.com
description: Player's email-address. Only present when it's your own information or you have admin rights.
email_validated:
description: Name of the player
example: Bob
is_admin:
type: boolean
readOnly: true
description: Was the player's email address successfully validated. Only present when it's your own information or you have admin rights.
description: Has the player administrator rights?
avatar:
$ref: '#/components/schemas/Image'
avatar_file:
$ref: '#/components/schemas/File'
PlayerDetailsModel:
allOf:
- $ref: '#/components/schemas/PlayerModel'
- type: object
properties:
email:
type: string
example: bob@example.com
description: Player's email-address. Only present when it's your own information or you have admin rights.
email_validated:
type: boolean
readOnly: true
description: Was the player's email address successfully validated. Only present when it's your own information or you have admin rights.
profile_text:
type: string
description: A self-description of the player with Markdown formatting
@ -138,8 +177,92 @@ components:
type: boolean
description: Has the user accepted the terms of service? Only needed for registration
writeOnly: true
CharacterModel:
allOf:
- $ref: '#/components/schemas/Timestamps'
- type: object
properties:
id:
type: integer
description: ID of the character
example: 1
readOnly: true
name:
type: string
description: (Current) name of the character
example: Groot
player:
$ref: '#/components/schemas/PlayerReference'
description:
type: string
description: A description of the character, formatted in Markdown
example: I am Groot
is_private:
type: boolean
description: Is this character only visible for it's owner?
avatar:
$ref: '#/components/schemas/Image'
avatar_file:
$ref: '#/components/schemas/File'
avatar_attribution:
type: string
description: Attribution for the character image, formatted in Markdown
example: CC-BY-SA [xx](https://example.com)
revision:
type: integer
description: Revision number of the character
example: 5
readOnly: true
rpg_system_id:
type: integer
description: ID of the RPG system to which the character belongs, if any
example: 6
rpg_system_name:
type: string
description: Name of the RPG system referenced by `rpg_system_id`.
example: Cryptomancer
readOnly: true
session_character:
type: boolean
description: Is the character a session character? Session characters exist only for a single session. It's most likely a copy of a regular character that go assigned to a player during a session.
readOnly: true
CharacterDetailsModel:
allOf:
- $ref: '#/components/schemas/CharacterModel'
- type: object
properties:
cml:
type: string
description: XML (CML) containing the character information
comment:
type: string
description: Commit comment of the latest character revision, Markdown formatted
CharacterRevision:
allOf:
- $ref: '#/components/schemas/TimestampCreated'
type: object
properties:
revision:
type: integer
description: Revision number
example: 5
comment:
type: string
description: Commit comment, Markdown formatted.
example: Leveled up!
security:
- bearer: [ ]
tags:
- name: Server Information
description: Information about the used API endpoint
- name: Authorization
description: Endpoints to authenticate a user
- name: Players
description: Endpoint for player registration and self-service
- name: Characters
description: Endpoint for Character browsing and management
- name: Admin
description: Endpoints at which admins can use their privileges over normal users
paths:
/info:
get:
@ -522,3 +645,297 @@ paths:
'application/json':
schema:
$ref: '#/components/schemas/Error'
/1.0/characters:
get:
tags:
- "Characters"
description: Search for characters
parameters:
- name: q
in: query
description: Query string to search for in character names
schema:
type: string
- name: limit
in: query
description: Maximum number of found characters to be returned
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: offset
in: query
description: Offset of the provided results from the first result, used for pagination of the results
schema:
type: integer
minimum: 0
default: 0
responses:
200:
description: Characters found in search. Private characters are not displayed unless they belong to the current player. Session characters are never displayed.
content:
'application/json':
schema:
type: object
properties:
offset:
type: integer
description: Offset of the first returned result from the first result in the database
query:
type: string
description: Query string used
characters:
type: array
items:
$ref: '#/components/schemas/CharacterModel'
post:
tags:
- "Characters"
description: Create a new character
requestBody:
$ref: '#/components/schemas/CharacterDetailsModel'
responses:
201:
description: Character was created
content:
'application/json':
schema:
$ref: '#/components/schemas/CharacterDetailsModel'
400:
description: Something is wrong with the provided character
content:
'application/json':
schema:
$ref: '#/components/schemas/ErrorWithFields'
401:
description: You are not logged in
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
/1.0/characters/{id}:
get:
tags:
- "Characters"
- "Admin"
description: Get a details on a single character
parameters:
- name: id
in: path
schema:
type: integer
description: ID of the character
required: true
- name: rev
in: query
schema:
type: integer
description: Revision number of the character. If omnitted, the most recent version of the character is returned.
required: false
responses:
200:
description: The details of the character
content:
'application/json':
schema:
$ref: '#/components/schemas/CharacterDetailsModel'
400:
description: Requested revision does not exist within character
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
401:
description: This is a private character and you are not logged in
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
403:
description: This is a private character and you are neither the owner nor an admin
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
patch:
tags:
- "Characters"
description: Update a character. You can also upload an XSLT document to patch the character CML.
parameters:
- name: id
in: path
schema:
type: integer
description: ID of the character
required: true
- name: comment
in: query
schema:
type: string
description: Optional commit comment, Markdown formatted
requestBody:
content:
'application/json':
schema:
allOf:
- $ref: '#/components/schemas/CharacterDetailsModel'
- type: object
properties:
latest_revision:
type: integer
description: The latest know revision of the character known to you. The request will be rejected with a 400 if this does not match the latest revision known to the database.
'application/xml':
schema:
type: string
example: |
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns="http://www.w3.org/TR/REC-html40">
<xsl:output method="xml"/>
<xsl:template match="node()|@*">
<xsl:copy>
<xsl:apply-templates select="node()|@*"/>
</xsl:copy>
</xsl:template>
<xsl:template match="@value[parent::attribute and ../@name='attr']">
<xsl:attribute name="value">
<xsl:value-of select="'23'"/>
</xsl:attribute>
</xsl:template>
</xsl:stylesheet>
responses:
200:
description: Character was successfully updated
content:
'application/json':
schema:
$ref: '#/components/schemas/CharacterDetailsModel'
400:
description: There is something wrong with the data you provided
content:
'application/json':
schema:
$ref: '#/components/schemas/ErrorWithFields'
401:
description: You are not logged in
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
403:
description: You are not the owner of the character
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
delete:
tags:
- "Characters"
- "Admin"
description: Deletes a character
parameters:
- name: id
in: path
schema:
type: integer
description: ID of the character
required: true
responses:
200:
description: Character was deleted
content:
'application/json':
schema:
$ref: '#/components/schemas/CharacterModel'
401:
description: You are not logged in
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
403:
description: You are neither the character's owner nor an admin
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
/1.0/characters/{id}/history:
get:
tags:
- "Characters"
description: Gets information about character revisions
parameters:
- name: id
in: path
schema:
type: integer
description: ID of the character
required: true
responses:
200:
description: Information about the character's revisions, latest revision first
content:
'application/json':
schema:
type: array
items:
$ref: '#/components/schemas/CharacterRevision'
401:
description: This is a private character and you are not logged in
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
403:
description: This is a private character and you are neither the owner nor the admin
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
/1.0/characters/{id]/history/{revision}:
delete:
tags:
- "Characters"
description: Deletes a single revision from a character. This will not affect previous nor later revisions. Think of a character revision as a snapshot rather than a set of changes. You cannot delete the last remaining revision of a character.
parameters:
- name: id
in: path
schema:
type: integer
description: ID of the character
required: true
- name: revision
in: path
schema:
type: integer
description: Revision number within character to delete
required: true
responses:
200:
description: Revision was deleted
content:
'application/json':
schema:
$ref: '#/components/schemas/CharacterRevision'
400:
description: Revision does not exist within character or this is the last remaining revision of this character
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
401:
description: You are not logged in.
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'
403:
description: You are not the owner of the character
content:
'application/json':
schema:
$ref: '#/components/schemas/Error'

2
swagger/Readme.md

@ -2,4 +2,4 @@
This is a copy of the [Swagger] release `dist/` directory configured to serve the swagger documentation while development. Open [index.html](index.html) in your browser.
The actual OpenAPI file is at [../openapi.yaml](../openapi.yaml).
The actual OpenAPI file is at [../public/openapi.yaml](../public/openapi.yaml).

2
swagger/swagger-initializer.js

@ -3,7 +3,7 @@ window.onload = function() {
// the following lines will be replaced by docker/configurator, when it runs in a docker-container
window.ui = SwaggerUIBundle({
url: "../openapi.yaml",
url: "../public/openapi.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [

Loading…
Cancel
Save