diff --git a/docs/REST API Reference/Reference.yaml b/docs/REST API Reference/Reference.yaml
index a3e29ad..05e358f 100644
--- a/docs/REST API Reference/Reference.yaml
+++ b/docs/REST API Reference/Reference.yaml
@@ -589,7 +589,9 @@ paths:
"$ref": "#/components/schemas/ErrorModel"
"/documents/{id}.{format}":
get:
- summary: Get Document
+ summary: Get Document by ID
+ description: Get specific document and its information.
+ operationId: getDocument
tags:
- Document
parameters:
@@ -600,7 +602,7 @@ paths:
schema:
type: integer
- name: format
- description: specify format of response
+ description: Specify the format of the response
in: path
required: true
schema:
@@ -610,7 +612,7 @@ paths:
- xml
responses:
'200':
- description: detail of Document
+ description: Retrieved detail of the Document
content:
application/json:
schema:
@@ -640,11 +642,13 @@ paths:
"$ref": "#/components/schemas/ErrorModel"
put:
summary: Update Document
+ description: Use this endpoint to update information of a document.
+ operationId: updateDocument
tags:
- Document
parameters:
- name: format
- description: specify format of response
+ description: Specify format of response
in: path
required: true
schema:
@@ -659,7 +663,7 @@ paths:
schema:
type: integer
requestBody:
- description: Update given Document
+ description: Request body of the document to be updated
required: true
content:
application/json:
@@ -673,7 +677,7 @@ paths:
"$ref": "#/components/schemas/DocumentApiRequest"
responses:
'200':
- description: updated
+ description: Document successfully updated
content:
application/json:
schema:
@@ -711,12 +715,14 @@ paths:
schema:
"$ref": "#/components/schemas/ErrorModel"
delete:
- summary: Destroy Document
+ summary: Delete Document
+ description: Use this endpoint to delete a specific document
+ operationId: deleteDocument
tags:
- Document
parameters:
- name: format
- description: specify format of response
+ description: Specify format of response
in: path
required: true
schema:
@@ -732,7 +738,7 @@ paths:
type: integer
responses:
'204':
- description: ok
+ description: Document deleted
'401':
description: not authorized
'403':
@@ -752,13 +758,15 @@ paths:
"$ref": "#/components/schemas/ErrorModel"
"/projects/{project_id}/documents.{format}":
get:
- summary: Retrieve documents of the Project with specified id
+ summary: Retrieve all documents of the Project with a specified ID
+ description: Retrieve all documents related to the project specified by ID
+ operationId: getDocumentsForProject
tags:
- Document
- Project documents
parameters:
- name: format
- description: specify format of response
+ description: Specify the format of the response
in: path
required: true
schema:
@@ -768,7 +776,7 @@ paths:
- xml
- name: project_id
in: path
- description: ID of Project
+ description: Project ID for which the documents will be retrieved
required: true
schema:
type: integer
@@ -811,12 +819,14 @@ paths:
"$ref": "#/components/schemas/ErrorModel"
post:
summary: Create a document in the Project with specified id
+ description: Create a document for a specific project.
+ operationId: createDocumentForProject
tags:
- Document
- Project documents
parameters:
- name: format
- description: specify format of response
+ description: Specify the format of the response
in: path
required: true
schema:
@@ -826,12 +836,12 @@ paths:
- xml
- name: project_id
in: path
- description: ID of Project
+ description: Project ID for which the document will be created
required: true
schema:
type: integer
requestBody:
- description: Create Document
+ description: Request body for document creation
required: true
content:
application/json:
@@ -845,7 +855,7 @@ paths:
"$ref": "#/components/schemas/ProjectDocumentApiRequest"
responses:
'201':
- description: created
+ description: Document created
content:
application/json:
schema:
@@ -885,12 +895,14 @@ paths:
"/easy_async_exports.{format}":
get:
summary: List of EasyAsyncExports
- description: For filtering send parameter `set_filter=1` and specify filters
+ description: Lists all asynchronous exports.
+ For filtering send parameter `set_filter=1` and specify filters.
+ operationId: getAsyncExports
tags:
- Easy async export
parameters:
- name: format
- description: specify format of response
+ description: Specify the format of the response
in: path
required: true
schema:
@@ -899,29 +911,32 @@ paths:
- json
- xml
- name: easy_query_q
- description: free-text filter of current entity
+ description: Free-text filter of current entity
in: query
+ example: john doe
schema:
type: string
- name: set_filter
description: enable filter through Easy Query
in: query
+ example: true
schema:
type: boolean
- name: limit
- description: the number of items to be present in the response (default is
- 25, maximum is 100)
+ description: Limits the number of returned results. Minimum is 25, maximum is 100.
in: query
+ example: 100
schema:
type: integer
- name: offset
- description: the offset of the first object to retrieve
+ description: Offset from the first record to retrieve
+ example: 100
in: query
schema:
type: integer
responses:
'200':
- description: ok
+ description: List of async exports
content:
application/json:
schema:
@@ -933,16 +948,19 @@ paths:
total_count:
type: number
example: 75
+ description: Total count of exports present
xml:
attribute: true
offset:
type: number
- example: 0
+ description: Offset applied for the set of returned data
+ example: 50
xml:
attribute: true
limit:
type: number
example: 25
+ description: Limit applied to this request. It describes the maximum number of results returned in the response.
xml:
attribute: true
easy_async_exports:
@@ -959,32 +977,37 @@ paths:
total_count:
type: number
example: 75
+ description: Total count of exports present
xml:
attribute: true
offset:
type: number
+ description: Offset applied for the set of returned data
example: 0
xml:
attribute: true
limit:
type: number
example: 25
+ description: Limit applied to this request. It describes the maximum number of results returned in the response.
xml:
attribute: true
easy_async_exports:
type: array
+ description: List of asynchronous exports
items:
"$ref": "#/components/schemas/EasyAsyncExportApiResponse"
'401':
description: not authorized
"/easy_async_exports/{id}.{format}":
delete:
- summary: Destroy EasyAsyncExport
+ summary: Delete EasyAsynchexport
+ description: Delete a single record of EasyAsyncExport using its ID.
tags:
- Easy async export
parameters:
- name: format
- description: specify format of response
+ description: Specify the format of the response
in: path
required: true
schema:
@@ -994,13 +1017,14 @@ paths:
- xml
- name: id
in: path
- description: ID of EasyAsyncExport
+ description: ID of the EasyAsyncExport
required: true
+ example: 2
schema:
type: integer
responses:
'204':
- description: ok
+ description: EasyAsyncExport deleted
'401':
description: not authorized
'403':
@@ -12325,20 +12349,28 @@ components:
type: integer
readOnly: true
example: 1
+ description: ID of the attachment in Easy Software
filename:
example: service-agreement.odt
type: string
+ description: Filename of the attachment
filesize:
type: integer
- example: '451564'
+ example: 451564
+ description: Size of the attachment in bytes
content_type:
example: application/vnd.oasis.opendocument.text
type: string
+ description: Content type of the document. Provides additional information for applications
content_url:
format: uri
type: string
+ example: https://easysoftware.com/file/1
+ description: URL through which the document can be accessed
description:
type: string
+ example: This attachment describes the project goal.
+ description: Description of the attachemnt shown to the user
href_url:
format: uri
type: string
@@ -12347,15 +12379,22 @@ components:
format: uri
type: string
author:
- title: User
+ title: User object
type: object
properties:
id:
type: integer
- name: {}
+ example: 15
+ description: ID of the user who uploaded the attachment
+ name:
+ type: string
+ example: John Doe
+ description: Name of the user who created the attachment
created_on:
format: date-time
type: string
+ example: 2001-12-15T02:59:43.1Z
+ description: Datetime when the attachment was created
xml:
name: attachment
AttachmentApiResponse:
@@ -12364,13 +12403,16 @@ components:
type: integer
readOnly: true
example: 1
- "$ref": "#/components/schemas/Attachment"
+ description: ID of the attachment in Easy Software
+ "$ref": "#/components/schemas/Attachment"
xml:
name: attachment
UploadResponse:
properties:
id:
type: integer
+ example: 1
+ description: ID of the uploaded file
token:
type: string
xml:
@@ -12767,17 +12809,24 @@ components:
DocumentApiRequest:
properties:
title:
- example: ''
+ example: Project lineout
+ description: Name of the document to be created
type: string
description:
- example: ''
+ example: This document describes project lineout
+ description: Description of the file, shown to the user
type: string
project_id:
type: integer
+ description: ID of the project the document will be linked to
+ example: 15
category_id:
type: integer
+ description: ID of the document category, used for filtering
+ example: 3
custom_fields:
type: array
+ description: Custom fields to be filled related to the document
items:
"$ref": "#/components/schemas/CustomFieldValueApiRequest"
required:
@@ -12792,38 +12841,52 @@ components:
type: integer
readOnly: true
example: 1
+ description: ID of the document in Easy Software
title:
- example: ''
+ example: Project outline
type: string
+ description: Name of the document
description:
- example: ''
+ example: This document describes the project outline
type: string
+ description: Description of the document shown to the user
project:
type: object
+ description: Project parameters object
readOnly: true
properties:
id:
type: integer
+ description: ID of the project document will be linked to
+ example: 15
xml:
attribute: true
name:
type: string
+ description: Name of the project document will be linked to
+ example: Easy Project
xml:
attribute: true
category:
type: object
readOnly: true
+ description: Object that describes the category of the document
properties:
id:
type: integer
+ description: ID of the category the document belongs to
+ example: 4
xml:
attribute: true
name:
type: string
+ description: Name of the category the document belongs to
+ example: Project documents
xml:
attribute: true
custom_fields:
type: array
+ description: Array of custom fields related to the document
xml:
wrapped: true
items:
@@ -12838,6 +12901,8 @@ components:
created_on:
type: string
format: date-time
+ description: Date time format when the document was created
+ example: 2001-12-15T02:59:43.1Z
readOnly: true
xml:
name: document
@@ -12851,6 +12916,7 @@ components:
type: string
documents:
type: array
+ description: List of documents related to the project
items:
"$ref": "#/components/schemas/DocumentApiResponse"
title: DocumentsGroup
@@ -12862,18 +12928,19 @@ components:
type: integer
readOnly: true
example: 1
+ description: ID of the asynchronous export
format:
type: string
example: csv
- description: Export format
+ description: Format of the exported file
title:
type: string
example: Csv export
- description: Export title
+ description: Title of the export
filename:
type: string
example: tasks.csv
- description: Export filename
+ description: Name of the exported file
status:
type: string
example: done
@@ -12892,22 +12959,31 @@ components:
"$ref": "#/components/schemas/Attachment"
author:
type: object
+ description: Information about the author of the export who initiated it
readOnly: true
properties:
id:
type: integer
+ description: ID of the author/initiator of the export
+ example: 15
xml:
attribute: true
name:
type: string
+ example: John Doe
+ description: Name of the author/initiator of the export
xml:
attribute: true
created_at:
type: string
format: date-time
readOnly: true
+ description: Datetime when the export was done
+ example: 2001-12-15T02:59:43.1Z
updated_at:
type: string
+ description: Datetime when the export was updated
+ example: 2001-12-15T02:59:43.1Z
format: date-time
readOnly: true
xml:
@@ -19076,15 +19152,20 @@ components:
ProjectDocumentApiRequest:
properties:
title:
- example: ''
+ example: Project outline.docx
+ description: Name of the document
type: string
description:
- example: ''
+ example: This document describes the project outline
+ description: Description of the document shown to the user
type: string
category_id:
type: integer
+ description: ID of the category the document is related to
+ example: 3
custom_fields:
type: array
+ description: List of custom fields related to the document
items:
"$ref": "#/components/schemas/CustomFieldValueApiRequest"
required:
@@ -20146,3 +20227,5 @@ components:
type: apiKey
name: key
in: query
+: key
+ in: query
diff --git a/reference/Reference_test.yaml b/reference/Reference_test.yaml
index daad8ab..a337f4c 100644
--- a/reference/Reference_test.yaml
+++ b/reference/Reference_test.yaml
@@ -406,11 +406,14 @@ paths:
"/custom_fields.{format}":
post:
summary: Create CustomField
+ operationId: createCustomField
+ description: Use this method to create a new custom field.
+ You can specify custom fields for issues, projects or users. This custom field will then be only available for the specified entity within the specified project
tags:
- Custom field
parameters:
- name: format
- description: specify format of response
+ description: Specify format of response
in: path
required: true
schema:
@@ -12506,12 +12509,12 @@ components:
properties:
name:
type: string
- example: auta
- description: Name of custom field
+ example: Internal identifying number shown to users
+ description: Name of the custom field
field_format:
type: string
example: list
- description: Format
+ description: Format of the custom field
enum:
- string
- text
@@ -12541,47 +12544,47 @@ components:
- flag
regexp:
type: string
- description: Regular expression
+ description: Regular expression for field validation
min_length:
type: integer
- description: Minimum length
+ description: Minimum length of the input
max_length:
type: integer
- description: Maximum length
+ description: Maximum length of the input
is_required:
type: boolean
- description: Required
+ description: Logical value whether the field is required
is_for_all:
type: boolean
- description: For all projects
+ description: Logical value whether the field will be available for all projects
is_filter:
type: boolean
- description: Used as a filter
+ description: Logical value whether the field can be used for filtering
position:
type: integer
example: 2
- description: Position of custom field in list
+ description: Position of custom field in the list
searchable:
type: boolean
- description: is searchable ?
+ description: Logical value whether the field can be used for search
default_value:
type: string
- description: Default value
+ description: Default value of the field
editable:
type: boolean
- description: Editable
+ description: Logical value whether the field is editable
visible:
type: boolean
- description: Visible
+ description: Logical value whether the field is visible
multiple:
type: boolean
- description: Multiple values
+ description: Logical value whether the field can have multiple values
description:
type: string
- description: Description
+ description: Description of the custom filed shown to the users
is_primary:
type: boolean
- description: Primary
+ description: Logical value whether the field is primary
show_empty:
type: boolean
description: Show with empty fields
@@ -12593,10 +12596,10 @@ components:
description: Its Hash object
internal_name:
type: string
- description: ''
+ description: Internal name of the field
show_on_more_form:
type: boolean
- example: 'true'
+ example: true
description: Show as additional attribute
easy_external_id:
type: string
@@ -12611,14 +12614,14 @@ components:
description: ''
mail_notification:
type: boolean
- example: 'true'
+ example: true
description: Email notifications
easy_group_id:
type: integer
description: ''
clear_when_anonymize:
type: boolean
- description: Clear when anonymize
+ description: Whether to clear the field when data is anonymized
possible_values:
type: array
xml: