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