mirror of
https://github.com/wassname/talk.git
synced 2026-08-15 12:55:10 +08:00
Add swagger user docs and tools page
This commit is contained in:
David Erwin
@@ -14,6 +14,9 @@ entries:
|
||||
- title: FAQ
|
||||
url: /faq.html
|
||||
output: web
|
||||
- title: Tools
|
||||
url: /tools.html
|
||||
output: web
|
||||
|
||||
- title: Installation
|
||||
output: web
|
||||
|
||||
@@ -0,0 +1,504 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: Talk API
|
||||
description: A commenting platform from The Coral Project. https://coralproject.net
|
||||
version: "0.0.1"
|
||||
host: talk-stg.coralproject.net
|
||||
schemes:
|
||||
- https
|
||||
basePath: /api/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
|
||||
paths:
|
||||
/users:
|
||||
get:
|
||||
parameters:
|
||||
- name: value
|
||||
in: query
|
||||
type: string
|
||||
description: A term to search users' usernames and email addresses.
|
||||
- name: sort
|
||||
in: query
|
||||
type: string
|
||||
enum:
|
||||
- asc
|
||||
- desc
|
||||
description: Determines whether users sorted in are ascending or descending order.
|
||||
- name: field
|
||||
in: query
|
||||
type: string
|
||||
description: The field used to sort.
|
||||
- name: page
|
||||
in: query
|
||||
type: number
|
||||
description: The page of search results to return.
|
||||
- name: limit
|
||||
in: query
|
||||
type: number
|
||||
description: The number of search restults per page.
|
||||
responses:
|
||||
200:
|
||||
description: A paginated array of users matching search terms.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
result:
|
||||
type: array
|
||||
description: Users matching search criteria.
|
||||
items:
|
||||
$ref: '#/definitions/User'
|
||||
limit:
|
||||
type: number
|
||||
description: Results per page.
|
||||
count:
|
||||
type: number
|
||||
description: Total number of results.
|
||||
page:
|
||||
type: number
|
||||
description: The current page.
|
||||
totalPages:
|
||||
type: number
|
||||
description: The total number of pages.
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
post:
|
||||
parameters:
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
description: User to be created.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
format: email
|
||||
password:
|
||||
type: string
|
||||
username:
|
||||
type: string
|
||||
responses:
|
||||
201:
|
||||
description: The user that has been created.
|
||||
schema:
|
||||
$ref: '#/definitions/User'
|
||||
/account/password/reset:
|
||||
post:
|
||||
parameters:
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: The token that was in the url of the email link.
|
||||
password:
|
||||
type: string
|
||||
description: The new password.
|
||||
responses:
|
||||
204:
|
||||
description: Password update successful.
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/request-password-reset:
|
||||
post:
|
||||
parameters:
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
email:
|
||||
type: string
|
||||
description: The email address of the user whos password is being reset.
|
||||
responses:
|
||||
204:
|
||||
description: Returned regardless of whether the user was found in the DB.
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/users/{user_id}/role:
|
||||
post:
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
type: string
|
||||
format: uuid
|
||||
description: ID of the user to be updated.
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
role:
|
||||
type: string
|
||||
description: Role to be added to the user.
|
||||
enum:
|
||||
- admin
|
||||
- moderator
|
||||
responses:
|
||||
204:
|
||||
description: Role update successful.
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/users/{user_id}/status:
|
||||
post:
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
type: string
|
||||
format: uuid
|
||||
required: true
|
||||
description: ID of the user to be updated.
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
description: Status for the user to be set to.
|
||||
enum:
|
||||
- active
|
||||
- banned
|
||||
comment_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: The id of the comment which triggered this status change.
|
||||
responses:
|
||||
200:
|
||||
description: Status update successful.
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/users/{user_id}/bio:
|
||||
put:
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
type: string
|
||||
format: uuid
|
||||
description: The id of the user being updated.
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
bio:
|
||||
type: string
|
||||
description: The bio that should be set for this user.
|
||||
responses:
|
||||
200:
|
||||
description: Status update successful.
|
||||
schema:
|
||||
$ref: '#/definitions/User'
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
/{user_id}/actions:
|
||||
post:
|
||||
parameters:
|
||||
- name: user_id
|
||||
in: path
|
||||
required: true
|
||||
type: string
|
||||
format: uuid
|
||||
description: The user on which this action is being taken.
|
||||
- name: body
|
||||
in: body
|
||||
required: true
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
action_type:
|
||||
description: The type of action being taken on this user.
|
||||
type: string
|
||||
enum:
|
||||
- flag
|
||||
metadata:
|
||||
type: object
|
||||
description: Arbitrary data to be included with the action.
|
||||
responses:
|
||||
200:
|
||||
description: The newly created action.
|
||||
schema:
|
||||
$ref: '#/definitions/Action'
|
||||
500:
|
||||
description: An error occured.
|
||||
schema:
|
||||
$ref: '#/definitions/Error'
|
||||
|
||||
definitions:
|
||||
Error:
|
||||
type: object
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
description: The error that occured.
|
||||
Comment:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Unique identifier
|
||||
body:
|
||||
type: string
|
||||
description: Description of comment
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Display name of comment
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Display name of comment
|
||||
author_id:
|
||||
type: string
|
||||
description: User who posted the comment
|
||||
parent_id:
|
||||
type: string
|
||||
description: Display name of comment
|
||||
asset_id:
|
||||
type: string
|
||||
description: Display name of comment
|
||||
status_history:
|
||||
type: array
|
||||
description: A history of status changes for this comment.
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- accepted
|
||||
- rejected
|
||||
- premod
|
||||
assigned_by:
|
||||
type: string
|
||||
description: ID of the user who assigned this status.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Date when status was assigned.
|
||||
|
||||
Actions:
|
||||
type: object
|
||||
description: A summary of actions taken on a particular item which is with the comment stream.
|
||||
properties:
|
||||
item_id:
|
||||
type: string
|
||||
description: The ID of the item which these actions target
|
||||
item_type:
|
||||
type: string
|
||||
description: The type of item which these actions target (comment, user, etc.)
|
||||
type:
|
||||
type: string
|
||||
description: The type of action (like, flag, etc.)
|
||||
count:
|
||||
type: integer
|
||||
description: The number of this type of actions performed on this item.
|
||||
metadata:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
description: Metadata from the actions performed on this item. This metadata can be defined differently for each action type.
|
||||
current_user:
|
||||
type: object
|
||||
description: Will include the action performed by the currently logged in user if that user has taken an action on this item. Otherwise will return null.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Oldest created_at of actions in this set.
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Newest updated_at of actions in this set.
|
||||
Action:
|
||||
type: object
|
||||
description: A single action taken by a user.
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The uuid.v4 id of the action.
|
||||
type:
|
||||
type: string
|
||||
description: The type of action being taken (like, flag, etc.)
|
||||
user_id:
|
||||
type: string
|
||||
description: The ID of the user taking this action.
|
||||
metadata:
|
||||
type: object
|
||||
description: An object which contains arbitrary metadata about the action. Should be consistent for each action_type.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Creation Date-Time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Updated Date-Time
|
||||
Asset:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The uuid.v4 id of the asset.
|
||||
url:
|
||||
type: string
|
||||
description: The url where the asset is found.
|
||||
type:
|
||||
type: string
|
||||
description: What kind of asset it is.
|
||||
default: article
|
||||
headline:
|
||||
type: string
|
||||
description: The headline of the asset, inferred on initial load.
|
||||
summary:
|
||||
type: string
|
||||
description: A summary of the asset, inferred on initial load.
|
||||
section:
|
||||
type: string
|
||||
description: The section the asset is in.
|
||||
subsection:
|
||||
type: string
|
||||
description: The subsection that the asset is in.
|
||||
authors:
|
||||
type: string
|
||||
description: An array of the authors for this asset.
|
||||
publication_date:
|
||||
type: string
|
||||
format: datetime
|
||||
description: When this asset was published.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Creation Date-Time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Updated Date-Time
|
||||
User:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The uuid.v4 id of the user.
|
||||
username:
|
||||
type: string
|
||||
description: The name appearing next to the user's comments.
|
||||
disabled:
|
||||
type: boolean
|
||||
description: Indicates whether the user's account has been disabled (ie if the user is banned).
|
||||
password:
|
||||
type: string
|
||||
description: This provides a source of identity proof for users who login using the local provider. A local provider will be assumed for users who do not have any social profiles.
|
||||
profiles:
|
||||
type: array
|
||||
description: The array of identities for a given user. Any one user can have multiple profiles associated with them (eg facebook, google, etc.)
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: A unique identifier for the profile.
|
||||
provider:
|
||||
type: string
|
||||
description: The ame of the identity provider being used (e.g. 'facebook', 'twitter', etc.)
|
||||
roles:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Roles occupied by the user (e.g. 'ADMIN', 'MODERATOR', etc.)
|
||||
status:
|
||||
type: string
|
||||
description: The current status of the user in the system.
|
||||
enum:
|
||||
- active
|
||||
- banned
|
||||
settings:
|
||||
type: object
|
||||
description: User-specific settings
|
||||
properties:
|
||||
bio:
|
||||
type: string
|
||||
description: A bio visible to other users.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Creation Date-Time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Updated Date-Time
|
||||
Settings:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: The id of the settings object. Defaults to 1 for global settings.
|
||||
moderation:
|
||||
type: string
|
||||
enum:
|
||||
- pre
|
||||
- post
|
||||
description: Indicates whether moderation occurs before or after a comment is made publicly visible.
|
||||
infoBoxEnable:
|
||||
type: boolean
|
||||
description: Indicates whether an informational box will be shown above the comment input box.
|
||||
infoBoxContent:
|
||||
type: string
|
||||
description: The text to appear in the informational box.
|
||||
closedTimeout:
|
||||
type: number
|
||||
format: int32
|
||||
description: The time after which streams will be automatically closed in seconds. Null will keep streams open forever.
|
||||
closedMessage:
|
||||
type: string
|
||||
description: The message displayed when a stream is closed.
|
||||
wordlist:
|
||||
type: array
|
||||
description: A list of banned word which will cause a comment to be automatically rejected.
|
||||
items:
|
||||
type: string
|
||||
charCount:
|
||||
type: number
|
||||
format: int32
|
||||
description: The maximum number of characters allowed in a comment.
|
||||
charCountEnable:
|
||||
type: boolean
|
||||
description: Indicates whether a maximum character count should be enabled for comments.
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Creation Date-Time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Updated Date-Time
|
||||
Job:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
format: number
|
||||
state:
|
||||
format: string
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Tooling
|
||||
keywords: homepage
|
||||
sidebar: talk_sidebar
|
||||
permalink: plugins-client.html
|
||||
summary:
|
||||
---
|
||||
|
||||
## Debugging
|
||||
How we debug errors at Coral
|
||||
|
||||
### React Debugging
|
||||
For debugging React
|
||||
|
||||
#### React Developer Tools
|
||||
Another amazing tool for debugging React Applications. You can see where the props are, and much more.
|
||||
|
||||
[React Developer Tools Extension](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
|
||||
|
||||
|
||||
### Redux Debugging
|
||||
For debugging Redux
|
||||
|
||||
#### Redux Devtool Extension
|
||||
Redux Devtool is an amazing debug tool. You can easily see what' happening with the state, the payloads, and more.
|
||||
|
||||
[Redux Devtool Chrome Extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
|
||||
|
||||
[Redux Devtool Github Repo](https://github.com/zalmoxisus/redux-devtools-extension)
|
||||
|
||||
### GraphQL
|
||||
|
||||
Talk ships with GraphiQL, a live data layer IDE. We strongly recommend using GraphiQL early and often as you work with all things queries, mutations and subscriptions!
|
||||
|
||||
* [Install Talk](install-source.html).
|
||||
* Open http://localhost:3000/api/v1/graph/iql in your browser. (Note, your server an port may differ.)
|
||||
Reference in New Issue
Block a user