github.com/circl-dev/go-swagger@v0.31.0/examples/task-tracker/swagger.yml (about) 1 swagger: '2.0' 2 host: localhost:8322 3 basePath: /api 4 schemes: 5 - http 6 - https 7 produces: 8 - application/vnd.goswagger.examples.task-tracker.v1+json 9 consumes: 10 - application/vnd.goswagger.examples.task-tracker.v1+json 11 12 securityDefinitions: 13 api_key: 14 type: apiKey 15 name: token 16 in: query 17 token_header: 18 type: apiKey 19 name: X-Token 20 in: header 21 22 info: 23 version: "1.0.0" 24 title: Issue Tracker API 25 description: | 26 This application implements a very simple issue tracker. 27 It's implemented as an API which is described by this swagger spec document. 28 29 The go-swagger project uses this specification to test the code generation. 30 This document contains all possible values for a swagger definition. 31 This means that it exercises the framework relatively well. 32 termsOfService: /termsOfService.html 33 contact: 34 name: Issue Tracker API Team 35 email: nobody@nowhere.com 36 url: https://task-tracker.goswagger.io 37 license: 38 name: Apache 2.0 39 url: http://www.apache.org/licenses/LICENSE-2.0.html 40 41 tags: 42 - name: tasks 43 description: manages tasks 44 externalDocs: 45 description: | 46 An extensive explanation on what is possible can be found in the 47 support site for this application. 48 url: https://go-swagger.github.io/examples/tasklist/help/tasks.html 49 50 - name: milestones 51 description: manages milestones 52 externalDocs: 53 description: | 54 An extensive explanation on what is possible can be found in the 55 support site for this application. 56 url: https://go-swagger.github.io/examples/tasklist/help/milestones.html 57 58 externalDocs: 59 description: | 60 A much more elaborate guide to this application is available at the support 61 site. 62 url: https://go-swagger.github.io/examples/tasklist/help/tasks.html 63 64 paths: 65 /tasks: 66 get: 67 operationId: listTasks 68 tags: 69 - tasks 70 summary: Lists the tasks 71 description: | 72 Allows for specifying a number of filter parameters to 73 narrow down the results. 74 Also allows for specifying a **sinceId** and **pageSize** parameter 75 to page through large result sets. 76 parameters: 77 - name: sinceId 78 in: query 79 description: The last id that was seen. 80 type: integer 81 format: int64 82 required: false 83 84 - name: tags 85 description: the tags to filter by 86 in: query 87 type: array 88 uniqueItems: true 89 items: 90 type: string 91 92 - name: status 93 description: the status to filter by 94 in: query 95 type: array 96 uniqueItems: true 97 collectionFormat: pipes 98 items: 99 type: string 100 enum: ["open", "closed", "ignored", "rejected"] 101 102 - $ref: "#/parameters/pageSize" 103 104 responses: 105 default: 106 $ref: "#/responses/ErrorResponse" 107 200: 108 description: Successful response 109 headers: 110 # This is probably not the right place to put this kind of information in 111 # a public API, but I need a header in a response. 112 X-Last-Task-Id: 113 type: integer 114 format: int64 115 description: the last task id known to the application 116 schema: 117 title: TaskList 118 type: array 119 items: 120 $ref: "#/definitions/TaskCard" 121 422: 122 description: Validation error 123 schema: 124 $ref: "#/definitions/ValidationError" 125 post: 126 operationId: createTask 127 security: 128 - api_key: [] 129 - token_header: [] 130 tags: 131 - tasks 132 summary: "Creates a 'Task' object." 133 description: | 134 Allows for creating a task. 135 This operation requires authentication so that we know which user 136 created the task. 137 parameters: 138 - name: body 139 in: body 140 description: The task to create 141 required: true 142 schema: 143 $ref: "#/definitions/Task" 144 responses: 145 default: 146 $ref: "#/responses/ErrorResponse" 147 201: 148 description: Task created 149 headers: 150 Location: 151 type: string 152 format: uri 153 description: URL to the newly added Task 154 155 /tasks/{id}: 156 parameters: 157 - $ref: "#/parameters/idPathParam" 158 get: 159 operationId: getTaskDetails 160 tags: 161 - tasks 162 summary: Gets the details for a task. 163 description: | 164 The details view has more information than the card view. 165 You can see who reported the issue and who last updated it when. 166 167 There are also comments for each issue. 168 responses: 169 default: 170 $ref: "#/responses/ErrorResponse" 171 200: 172 description: Task details 173 schema: 174 $ref: "#/definitions/Task" 175 422: 176 description: Validation error 177 schema: 178 $ref: "#/definitions/ValidationError" 179 put: 180 operationId: updateTask 181 tags: 182 - tasks 183 summary: Updates the details for a task. 184 description: | 185 Allows for updating a task. 186 This operation requires authentication so that we know which user 187 last updated the task. 188 security: 189 - api_key: [] 190 - token_header: [] 191 parameters: 192 - name: body 193 in: body 194 description: The task to update 195 required: true 196 schema: 197 $ref: "#/definitions/Task" 198 responses: 199 default: 200 $ref: "#/responses/ErrorResponse" 201 200: 202 description: Task details 203 schema: 204 $ref: "#/definitions/Task" 205 422: 206 description: Validation error 207 schema: 208 $ref: "#/definitions/ValidationError" 209 210 delete: 211 operationId: deleteTask 212 tags: 213 - tasks 214 summary: Deletes a task. 215 description: | 216 This is a soft delete and changes the task status to ignored. 217 security: 218 - api_key: [] 219 - token_header: [] 220 responses: 221 default: 222 $ref: "#/responses/ErrorResponse" 223 204: 224 description: Task deleted 225 226 /tasks/{id}/comments: 227 parameters: 228 - $ref: "#/parameters/idPathParam" 229 post: 230 summary: Adds a comment to a task 231 description: | 232 The comment can contain ___github markdown___ syntax. 233 Fenced codeblocks etc are supported through pygments. 234 operationId: addCommentToTask 235 tags: 236 - tasks 237 security: 238 - api_key: [] 239 - token_header: [] 240 parameters: 241 - $ref: "#/parameters/idPathParam" 242 - name: body 243 in: body 244 description: The comment to add 245 schema: 246 title: A comment to create 247 description: | 248 These values can have github flavored markdown. 249 type: object 250 required: 251 - content 252 - userId 253 properties: 254 userId: 255 type: integer 256 format: int64 257 content: 258 type: string 259 responses: 260 default: 261 $ref: "#/responses/ErrorResponse" 262 201: 263 description: Comment added 264 get: 265 tags: 266 - tasks 267 operationId: getTaskComments 268 summary: Gets the comments for a task 269 description: | 270 The comments require a size parameter. 271 parameters: 272 - $ref: "#/parameters/pageSize" 273 - name: since 274 in: query 275 description: The created time of the oldest seen comment 276 type: string 277 format: date-time 278 required: false 279 responses: 280 default: 281 $ref: "#/responses/ErrorResponse" 282 200: 283 description: The list of comments 284 schema: 285 type: array 286 items: 287 $ref: "#/definitions/Comment" 288 289 290 /tasks/{id}/files: 291 parameters: 292 - $ref: "#/parameters/idPathParam" 293 post: 294 operationId: uploadTaskFile 295 summary: Adds a file to a task. 296 description: "The file can't be larger than **5MB**" 297 tags: 298 - tasks 299 consumes: 300 - multipart/form-data 301 security: 302 - api_key: [] 303 - token_header: [] 304 parameters: 305 - name: file 306 in: formData 307 description: The file to upload 308 type: file 309 - name: description 310 in: formData 311 description: Extra information describing the file 312 type: string 313 responses: 314 default: 315 $ref: "#/responses/ErrorResponse" 316 201: 317 description: File added 318 319 responses: 320 ErrorResponse: 321 description: Error response 322 headers: 323 X-Error-Code: 324 type: string 325 schema: 326 $ref: "#/definitions/Error" 327 328 329 parameters: 330 idPathParam: 331 name: id 332 description: The id of the item 333 type: integer 334 format: int64 335 in: path 336 required: true 337 338 pageSize: 339 name: pageSize 340 type: integer 341 format: int32 342 in: query 343 description: Amount of items to return in a single page 344 default: 20 345 346 definitions: 347 Error: 348 title: Error Structure 349 description: | 350 Contains all the properties any error response from the API will contain. 351 Some properties are optional so might be empty most of the time 352 type: object 353 required: 354 - code 355 - message 356 properties: 357 code: 358 description: the error code, this is not necessarily the http status code 359 type: integer 360 format: int32 361 message: 362 description: a human readable version of the error 363 type: string 364 helpUrl: 365 description: an optional url for getting more help about this error 366 type: string 367 format: uri 368 369 ValidationError: 370 allOf: 371 - $ref: "#/definitions/Error" 372 - type: object 373 properties: 374 field: 375 description: an optional field name to which this validation error applies 376 type: string 377 378 TaskCard: 379 title: a card for a task 380 description: | 381 A task card is a minimalistic representation of a task. Useful for display in list views, like a card list. 382 type: object 383 required: 384 - title 385 - status 386 properties: 387 id: 388 title: The id of the task. 389 description: A unique identifier for the task. These are created in ascending order. 390 type: integer 391 format: int64 392 readOnly: true 393 title: 394 title: The title of the task. 395 description: | 396 The title for a task, this needs to be at least 5 chars long. 397 Titles don't allow any formatting, besides emoji. 398 type: string 399 minLength: 5 400 maxLength: 150 401 description: 402 title: The description of the task. 403 description: | 404 The task description is a longer, more detailed description of the issue. 405 Perhaps it even mentions steps to reproduce. 406 type: string 407 milestone: 408 $ref: "#/definitions/Milestone" 409 severity: 410 type: integer 411 format: int32 412 minimum: 1 413 maximum: 5 414 effort: 415 description: the level of effort required to get this task completed 416 type: integer 417 format: int32 418 maximum: 27 419 multipleOf: 3 420 karma: 421 title: the karma donated to this item. 422 description: | 423 Karma is a lot like voting. Users can donate a certain amount or karma to an issue. 424 This is used to determine the weight users place on an issue. Not that +1 comments aren't great. 425 type: number 426 format: float32 427 minimum: 0 428 exclusiveMinimum: true 429 multipleOf: 0.5 430 status: 431 title: the status of the issue 432 description: | 433 There are 4 possible values for a status. 434 Ignored means as much as accepted but not now, perhaps later. 435 type: string 436 enum: ["open", "closed", "ignored", "rejected"] 437 assignedTo: 438 $ref: "#/definitions/UserCard" 439 reportedAt: 440 title: The time at which this issue was reported. 441 description: | 442 This field is read-only, so it's only sent as part of the response. 443 type: string 444 format: date-time 445 readOnly: true 446 tags: 447 title: task tags. 448 description: a task can be tagged with text blurbs. 449 type: array 450 uniqueItems: true 451 maxItems: 5 452 items: 453 pattern: \w[\w- ]+ 454 minLength: 3 455 type: string 456 457 Task: 458 title: a structure describing a complete task. 459 description: | 460 A Task is the main entity in this application. Everything revolves around tasks and managing them. 461 type: "object" 462 allOf: 463 - $ref: "#/definitions/TaskCard" 464 - type: object 465 properties: 466 lastUpdated: 467 title: The time at which this issue was last updated. 468 description: | 469 This field is read only so it's only sent as part of the response. 470 type: string 471 format: date-time 472 readOnly: true 473 reportedBy: 474 $ref: "#/definitions/UserCard" 475 lastUpdatedBy: 476 $ref: "#/definitions/UserCard" 477 comments: 478 title: The 5 most recent items for this issue. 479 description: | 480 The detail view of an issue includes the 5 most recent comments. 481 This field is read only, comments are added through a separate process. 482 readOnly: true 483 type: array 484 items: 485 $ref: "#/definitions/Comment" 486 attachments: 487 title: The attached files. 488 description: | 489 An issue can have at most 20 files attached to it. 490 type: object 491 additionalProperties: 492 type: object 493 maxProperties: 20 494 properties: 495 name: 496 title: The name of the file. 497 description: | 498 This name is inferred from the upload request. 499 type: string 500 readOnly: true 501 description: 502 title: Extra information to attach to the file. 503 description: | 504 This is a free form text field with support for github flavored markdown. 505 type: string 506 minLength: 3 507 url: 508 title: The url to download or view the file. 509 description: | 510 This URL is generated on the server, based on where it was able to store the file when it was uploaded. 511 type: string 512 format: uri 513 readOnly: true 514 contentType: 515 title: The content type of the file. 516 description: | 517 The content type of the file is inferred from the upload request. 518 type: string 519 readOnly: true 520 size: 521 title: The file size in bytes. 522 description: This property was generated during the upload request of the file. 523 type: number 524 format: float64 525 readOnly: true 526 Milestone: 527 title: A milestone is a particular goal that is important to the project for this issue tracker. 528 description: | 529 Milestones can have a escription and due date. 530 This can be useful for filters and such. 531 type: object 532 required: 533 - name 534 properties: 535 name: 536 title: The name of the milestone. 537 description: | 538 Each milestone should get a unique name. 539 type: string 540 pattern: "[A-Za-z][\\w- ]+" 541 minLength: 3 542 maxLength: 50 543 description: 544 type: string 545 title: The description of the milestone. 546 description: | 547 A description is a free text field that allows for a more detailed explanation of what the milestone is trying to achieve. 548 dueDate: 549 title: An optional due date for this milestone. 550 description: | 551 This property is optional, but when present it lets people know when they can expect this milestone to be completed. 552 type: string 553 format: date 554 stats: 555 title: Some counters for this milestone. 556 description: | 557 This object contains counts for the remaining open issues and the amount of issues that have been closed. 558 type: object 559 properties: 560 open: 561 title: The remaining open issues. 562 type: integer 563 format: int32 564 closed: 565 title: The closed issues. 566 type: integer 567 format: int32 568 total: 569 title: The total number of issues for this milestone. 570 type: integer 571 format: int32 572 Comment: 573 title: A comment for an issue. 574 description: | 575 Users can comment on issues to discuss plans for resolution etc. 576 type: object 577 required: 578 - user 579 - content 580 properties: 581 user: 582 $ref: "#/definitions/UserCard" 583 content: 584 title: The content of the comment. 585 description: | 586 This is a free text field with support for github flavored markdown. 587 type: string 588 createdAt: 589 title: The time at which this comment was created. 590 description: This field is autogenerated when the content is posted. 591 type: string 592 format: date-time 593 readOnly: true 594 595 UserCard: 596 title: A minimal representation of a user. 597 description: | 598 This representation of a user is mainly meant for inclusion in other models, or for list views. 599 type: object 600 required: 601 - id 602 - screenName 603 properties: 604 id: 605 title: A unique identifier for a user. 606 description: | 607 This id is automatically generated on the server when a user is created. 608 type: integer 609 format: int64 610 readOnly: true 611 screenName: 612 title: The screen name for the user. 613 description: | 614 This is used for vanity type urls as well as login credentials. 615 type: string 616 pattern: \w[\w_-]+ 617 minLength: 3 618 maxLength: 255 619 availableKarma: 620 title: The amount of karma this user has available. 621 description: | 622 In this application users get a cerain amount of karma alotted. 623 This karma can be donated to other users to show appreciation, or it can be used 624 by a user to vote on issues. 625 Once an issue is closed or rejected, the user gets his karma back. 626 type: number 627 format: float32 628 maximum: 1000 629 exclusiveMaximum: true 630 readOnly: true 631 admin: 632 title: When true this user is an admin. 633 description: | 634 Only employees of the owning company can be admins. 635 Admins are like project owners but have access to all the projects in the application. 636 There aren't many admins, and it's only used for extremly critical issues with the application. 637 type: boolean 638 readOnly: true