docs.md

Issue Tracker API

This application implements a very simple issue tracker. It's implemented as an API which is described by this swagger spec document.

The go-swagger project uses this specification to test the code generation. This document contains all possible values for a swagger definition. This means that it exercises the framework relatively well.

Read more

Version

1.0.0

License

Apache 2.0

Contact

Issue Tracker API Team nobody@nowhere.com https://task-tracker.goswagger.io

Terms Of Service

/termsOfService.html

Tags

tasks

milestones

URI Schemes

• http
• https

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json
• multipart/form-data

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Securtity Schemes

X-Token (header)

Type: apiKey

token (query)

Type: apiKey

Paths

Adds a comment to a task (addCommentToTask)

POST /api/tasks/{id}/comments

The comment can contain github markdown syntax. Fenced codeblocks etc are supported through pygments.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item
body	body	[body](#body)				The comment to add

Responses

Code	Type	Description
201		Comment added
default		The comment can contain ___github markdown___ syntax. Fenced codeblocks etc are supported through pygments.

Creates a 'Task' object. (createTask)

POST /api/tasks

Allows for creating a task. This operation requires authentication so that we know which user created the task.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
body	body	[body](#body)		✓		The task to create

Responses

Code	Type	Description
201		Task created
default		Allows for creating a task. This operation requires authentication so that we know which user created the task.

Deletes a task. (deleteTask)

DELETE /api/tasks/{id}

This is a soft delete and changes the task status to ignored.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item

Responses

Code	Type	Description
204		Task deleted
default		This is a soft delete and changes the task status to ignored.

Gets the comments for a task (getTaskComments)

GET /api/tasks/{id}/comments

The comments require a size parameter.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item
pageSize	query	int32			`20`	Amount of items to return in a single page
since	query	date-time				The created time of the oldest seen comment

Responses

Code	Type	Description
200		The list of comments
default		The comments require a size parameter.

Gets the details for a task. (getTaskDetails)

GET /api/tasks/{id}

The details view has more information than the card view. You can see who reported the issue and who last updated it when.

There are also comments for each issue.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item

Responses

Code	Type	Description
200		Task details
422		Validation error
default		The details view has more information than the card view. You can see who reported the issue and who last updated it when. There are also comments for each issue.

Lists the tasks (listTasks)

GET /api/tasks

Allows for specifying a number of filter parameters to narrow down the results. Also allows for specifying a sinceId and pageSize parameter to page through large result sets.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
pageSize	query	int32			`20`	Amount of items to return in a single page
sinceId	query	int64				The last id that was seen.
status	query	[]string	pipes			the status to filter by
tags	query	[]string	csv			the tags to filter by

Responses

Code	Type	Description
200		Successful response
422		Validation error
default		Allows for specifying a number of filter parameters to narrow down the results. Also allows for specifying a **sinceId** and **pageSize** parameter to page through large result sets.

Updates the details for a task. (updateTask)

PUT /api/tasks/{id}

Allows for updating a task. This operation requires authentication so that we know which user last updated the task.

Consumes

• application/vnd.goswagger.examples.task-tracker.v1+json

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item
body	body	[body](#body)		✓		The task to update

Responses

Code	Type	Description
200		Task details
422		Validation error
default		Allows for updating a task. This operation requires authentication so that we know which user last updated the task.

Adds a file to a task. (uploadTaskFile)

POST /api/tasks/{id}/files

The file can't be larger than 5MB

Consumes

• multipart/form-data

Produces

• application/vnd.goswagger.examples.task-tracker.v1+json

Parameters

Name	Source	Type	Separator	Required	Default	Description
id	path	int64		✓		The id of the item
description	formData	string				Extra information describing the file
file	formData	file				The file to upload

Responses

Code	Type	Description
201		File added
default		The file can't be larger than **5MB**

Models

Milestone

Milestones can have a escription and due date. This can be useful for filters and such.

Properties

Name	Type	Required	Description
description	string		A description is a free text field that allows for a more detailed explanation of what the milestone is trying to achieve.
dueDate	strfmt.Date		This property is optional, but when present it lets people know when they can expect this milestone to be completed.
name	string	✓	Each milestone should get a unique name.
stats	MilestoneStats

Task

A Task is the main entity in this application. Everything revolves around tasks and managing them.

Properties

Name	Type	Required	Description
	TaskCard
attachments	map[string]TaskAttachmentsAnon		An issue can have at most 20 files attached to it.
comments	[]*Comment		The detail view of an issue includes the 5 most recent comments. This field is read only, comments are added through a separate process.
lastUpdated	strfmt.DateTime		This field is read only so it's only sent as part of the response.
lastUpdatedBy	UserCard
reportedBy	UserCard

TaskCard

A task card is a minimalistic representation of a task. Useful for display in list views, like a card list.

Properties

Name	Type	Required	Description
assignedTo	UserCard
description	string		The task description is a longer, more detailed description of the issue. Perhaps it even mentions steps to reproduce.
effort	int32		the level of effort required to get this task completed
id	int64		A unique identifier for the task. These are created in ascending order.
karma	float64		Karma is a lot like voting. Users can donate a certain amount or karma to an issue. This is used to determine the weight users place on an issue. Not that +1 comments aren't great.
milestone	Milestone
reportedAt	strfmt.DateTime		This field is read-only, so it's only sent as part of the response.
severity	int32
status	string	✓	There are 4 possible values for a status. Ignored means as much as accepted but not now, perhaps later.
tags	[]string		a task can be tagged with text blurbs.
title	string	✓	The title for a task, this needs to be at least 5 chars long. Titles don't allow any formatting, besides emoji.

UserCard

This representation of a user is mainly meant for inclusion in other models, or for list views.

Properties

Name	Type	Required	Description
admin	bool		Only employees of the owning company can be admins. Admins are like project owners but have access to all the projects in the application. There aren't many admins, and it's only used for extremly critical issues with the application.
availableKarma	float64		In this application users get a cerain amount of karma alotted. This karma can be donated to other users to show appreciation, or it can be used by a user to vote on issues. Once an issue is closed or rejected, the user gets his karma back.
id	int64	✓	This id is automatically generated on the server when a user is created.
screenName	string	✓	This is used for vanity type urls as well as login credentials.

ValidationError

Properties

Name	Type	Required	Description
	Error
field	string		an optional field name to which this validation error applies

Comment

Users can comment on issues to discuss plans for resolution etc.

Properties

Name	Type	Required	Description
content	string	✓	This is a free text field with support for github flavored markdown.
createdAt	strfmt.DateTime		This field is autogenerated when the content is posted.
user	UserCard	✓

Error

Contains all the properties any error response from the API will contain. Some properties are optional so might be empty most of the time

Properties

Name	Type	Required	Description
code	int32	✓	the error code, this is not necessarily the http status code
helpUrl	strfmt.URI		an optional url for getting more help about this error
message	string	✓	a human readable version of the error