github.com/dirkm/go-swagger@v0.19.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  
   150    /tasks/{id}:
   151      parameters:
   152        - $ref: "#/parameters/idPathParam"
   153      get:
   154        operationId: getTaskDetails
   155        tags:
   156          - tasks
   157        summary: Gets the details for a task.
   158        description: |
   159          The details view has more information than the card view.
   160          You can see who reported the issue and who last updated it when.
   161  
   162          There are also comments for each issue.
   163        responses:
   164          default:
   165            $ref: "#/responses/ErrorResponse"
   166          200:
   167            description: Task details
   168            schema:
   169              $ref: "#/definitions/Task"
   170          422:
   171            description: Validation error
   172            schema:
   173              $ref: "#/definitions/ValidationError"
   174      put:
   175        operationId: updateTask
   176        tags:
   177          - tasks
   178        summary: Updates the details for a task.
   179        description: |
   180          Allows for updating a task.
   181          This operation requires authentication so that we know which user
   182          last updated the task.
   183        security:
   184          - api_key: []
   185          - token_header: []
   186        parameters:
   187          - name: body
   188            in: body
   189            description: The task to update
   190            required: true
   191            schema:
   192              $ref: "#/definitions/Task"
   193        responses:
   194          default:
   195            $ref: "#/responses/ErrorResponse"
   196          200:
   197            description: Task details
   198            schema:
   199              $ref: "#/definitions/Task"
   200          422:
   201            description: Validation error
   202            schema:
   203              $ref: "#/definitions/ValidationError"
   204  
   205      delete:
   206        operationId: deleteTask
   207        tags:
   208          - tasks
   209        summary: Deletes a task.
   210        description: |
   211          This is a soft delete and changes the task status to ignored.
   212        security:
   213          - api_key: []
   214          - token_header: []
   215        responses:
   216          default:
   217            $ref: "#/responses/ErrorResponse"
   218          204:
   219            description: Task deleted
   220  
   221    /tasks/{id}/comments:
   222      parameters:
   223        - $ref: "#/parameters/idPathParam"
   224      post:
   225        summary: Adds a comment to a task
   226        description: |
   227          The comment can contain ___github markdown___ syntax.
   228          Fenced codeblocks etc are supported through pygments.
   229        operationId: addCommentToTask
   230        tags:
   231          - tasks
   232        security:
   233          - api_key: []
   234          - token_header: []
   235        parameters:
   236          - $ref: "#/parameters/idPathParam"
   237          - name: body
   238            in: body
   239            description: The comment to add
   240            schema:
   241              title: A comment to create
   242              description: |
   243                These values can have github flavored markdown.
   244              type: object
   245              required:
   246                - content
   247                - userId
   248              properties:
   249                userId:
   250                  type: integer
   251                  format: int64
   252                content:
   253                  type: string
   254        responses:
   255          default:
   256            $ref: "#/responses/ErrorResponse"
   257          201:
   258            description: Comment added
   259      get:
   260        tags:
   261          - tasks
   262        operationId: getTaskComments
   263        summary: Gets the comments for a task
   264        description: |
   265          The comments require a size parameter.
   266        parameters:
   267          - $ref: "#/parameters/pageSize"
   268          - name: since
   269            in: query
   270            description: The created time of the oldest seen comment
   271            type: string
   272            format: date-time
   273            required: false
   274        responses:
   275          default:
   276            $ref: "#/responses/ErrorResponse"
   277          200:
   278            description: The list of comments
   279            schema:
   280              type: array
   281              items:
   282                $ref: "#/definitions/Comment"
   283  
   284  
   285    /tasks/{id}/files:
   286      parameters:
   287        - $ref: "#/parameters/idPathParam"
   288      post:
   289        operationId: uploadTaskFile
   290        summary: Adds a file to a task.
   291        description: "The file can't be larger than **5MB**"
   292        tags:
   293          - tasks
   294        consumes:
   295          - multipart/form-data
   296        security:
   297          - api_key: []
   298          - token_header: []
   299        parameters:
   300          - name: file
   301            in: formData
   302            description: The file to upload
   303            type: file
   304          - name: description
   305            in: formData
   306            description: Extra information describing the file
   307            type: string
   308        responses:
   309          default:
   310            $ref: "#/responses/ErrorResponse"
   311          201:
   312            description: File added
   313  
   314  responses:
   315    ErrorResponse:
   316      description: Error response
   317      headers:
   318        X-Error-Code:
   319          type: string
   320      schema:
   321        $ref: "#/definitions/Error"
   322  
   323  
   324  parameters:
   325    idPathParam:
   326      name: id
   327      description: The id of the item
   328      type: integer
   329      format: int64
   330      in: path
   331      required: true
   332  
   333    pageSize:
   334      name: pageSize
   335      type: integer
   336      format: int32
   337      in: query
   338      description: Amount of items to return in a single page
   339      default: 20
   340  
   341  definitions:
   342    Error:
   343      title: Error Structure
   344      description: |
   345        Contains all the properties any error response from the API will contain.
   346        Some properties are optional so might be empty most of the time
   347      type: object
   348      required:
   349        - code
   350        - message
   351      properties:
   352        code:
   353          description: the error code, this is not necessarily the http status code
   354          type: integer
   355          format: int32
   356        message:
   357          description: a human readable version of the error
   358          type: string
   359        helpUrl:
   360          description: an optional url for getting more help about this error
   361          type: string
   362          format: uri
   363  
   364    ValidationError:
   365      allOf:
   366        - $ref: "#/definitions/Error"
   367        - type: object
   368          properties:
   369            field:
   370              description: an optional field name to which this validation error applies
   371              type: string
   372  
   373    TaskCard:
   374      title: a card for a task
   375      description: |
   376        A task card is a minimalistic representation of a task. Useful for display in list views, like a card list.
   377      type: object
   378      required:
   379        - title
   380        - status
   381      properties:
   382        id:
   383          title: The id of the task.
   384          description: A unique identifier for the task. These are created in ascending order.
   385          type: integer
   386          format: int64
   387          readOnly: true
   388        title:
   389          title: The title of the task.
   390          description: |
   391            The title for a task, this needs to be at least 5 chars long.
   392            Titles don't allow any formatting, besides emoji.
   393          type: string
   394          minLength: 5
   395          maxLength: 150
   396        description:
   397          title: The description of the task.
   398          description: |
   399            The task description is a longer, more detailed description of the issue.
   400            Perhaps it even mentions steps to reproduce.
   401          type: string
   402        milestone:
   403          $ref: "#/definitions/Milestone"
   404        severity:
   405          type: integer
   406          format: int32
   407          minimum: 1
   408          maximum: 5
   409        effort:
   410          description: the level of effort required to get this task completed
   411          type: integer
   412          format: int32
   413          maximum: 27
   414          multipleOf: 3
   415        karma:
   416          title: the karma donated to this item.
   417          description: |
   418            Karma is a lot like voting.  Users can donate a certain amount or karma to an issue.
   419            This is used to determine the weight users place on an issue. Not that +1 comments aren't great.
   420          type: number
   421          format: float32
   422          minimum: 0
   423          exclusiveMinimum: true
   424          multipleOf: 0.5
   425        status:
   426          title: the status of the issue
   427          description: |
   428            There are 4 possible values for a status.
   429            Ignored means as much as accepted but not now, perhaps later.
   430          type: string
   431          enum: ["open", "closed", "ignored", "rejected"]
   432        assignedTo:
   433          $ref: "#/definitions/UserCard"
   434        reportedAt:
   435          title: The time at which this issue was reported.
   436          description: |
   437            This field is read-only, so it's only sent as part of the response.
   438          type: string
   439          format: date-time
   440          readOnly: true
   441        tags:
   442          title: task tags.
   443          description: a task can be tagged with text blurbs.
   444          type: array
   445          uniqueItems: true
   446          maxItems: 5
   447          items:
   448            pattern: \w[\w- ]+
   449            minLength: 3
   450            type: string
   451  
   452    Task:
   453      title: a structure describing a complete task.
   454      description: |
   455        A Task is the main entity in this application. Everything revolves around tasks and managing them.
   456      type: "object"
   457      allOf:
   458        - $ref: "#/definitions/TaskCard"
   459        - type: object
   460          properties:
   461            lastUpdated:
   462              title: The time at which this issue was last updated.
   463              description: |
   464                This field is read only so it's only sent as part of the response.
   465              type: string
   466              format: date-time
   467              readOnly: true
   468            reportedBy:
   469              $ref: "#/definitions/UserCard"
   470            lastUpdatedBy:
   471              $ref: "#/definitions/UserCard"
   472            comments:
   473              title: The 5 most recent items for this issue.
   474              description: |
   475                The detail view of an issue includes the 5 most recent comments.
   476                This field is read only, comments are added through a separate process.
   477              readOnly: true
   478              type: array
   479              items:
   480                $ref: "#/definitions/Comment"
   481            attachments:
   482              title: The attached files.
   483              description: |
   484                An issue can have at most 20 files attached to it.
   485              type: object
   486              additionalProperties:
   487                type: object
   488                maxProperties: 20
   489                properties:
   490                  name:
   491                    title: The name of the file.
   492                    description: |
   493                      This name is inferred from the upload request.
   494                    type: string
   495                    readOnly: true
   496                  description:
   497                    title: Extra information to attach to the file.
   498                    description: |
   499                      This is a free form text field with support for github flavored markdown.
   500                    type: string
   501                    minLength: 3
   502                  url:
   503                    title: The url to download or view the file.
   504                    description: |
   505                      This URL is generated on the server, based on where it was able to store the file when it was uploaded.
   506                    type: string
   507                    format: uri
   508                    readOnly: true
   509                  contentType:
   510                    title: The content type of the file.
   511                    description: |
   512                      The content type of the file is inferred from the upload request.
   513                    type: string
   514                    readOnly: true
   515                  size:
   516                    title: The file size in bytes.
   517                    description: This property was generated during the upload request of the file.
   518                    type: number
   519                    format: float64
   520                    readOnly: true
   521    Milestone:
   522      title: A milestone is a particular goal that is important to the project for this issue tracker.
   523      description: |
   524        Milestones can have a escription and due date.
   525        This can be useful for filters and such.
   526      type: object
   527      required:
   528        - name
   529      properties:
   530        name:
   531          title: The name of the milestone.
   532          description: |
   533            Each milestone should get a unique name.
   534          type: string
   535          pattern: "[A-Za-z][\\w- ]+"
   536          minLength: 3
   537          maxLength: 50
   538        description:
   539          type: string
   540          title: The description of the milestone.
   541          description: |
   542            A description is a free text field that allows for a more detailed explanation of what the milestone is trying to achieve.
   543        dueDate:
   544          title: An optional due date for this milestone.
   545          description: |
   546            This property is optional, but when present it lets people know when they can expect this milestone to be completed.
   547          type: string
   548          format: date
   549        stats:
   550          title: Some counters for this milestone.
   551          description: |
   552            This object contains counts for the remaining open issues and the amount of issues that have been closed.
   553          type: object
   554          properties:
   555            open:
   556              title: The remaining open issues.
   557              type: integer
   558              format: int32
   559            closed:
   560              title: The closed issues.
   561              type: integer
   562              format: int32
   563            total:
   564              title: The total number of issues for this milestone.
   565              type: integer
   566              format: int32
   567    Comment:
   568      title: A comment for an issue.
   569      description: |
   570        Users can comment on issues to discuss plans for resolution etc.
   571      type: object
   572      required:
   573        - user
   574        - content
   575      properties:
   576        user:
   577          $ref: "#/definitions/UserCard"
   578        content:
   579          title: The content of the comment.
   580          description: |
   581            This is a free text field with support for github flavored markdown.
   582          type: string
   583        createdAt:
   584          title: The time at which this comment was created.
   585          description: This field is autogenerated when the content is posted.
   586          type: string
   587          format: date-time
   588          readOnly: true
   589  
   590    UserCard:
   591      title: A minimal representation of a user.
   592      description: |
   593        This representation of a user is mainly meant for inclusion in other models, or for list views.
   594      type: object
   595      required:
   596        - id
   597        - screenName
   598      properties:
   599        id:
   600          title: A unique identifier for a user.
   601          description: |
   602            This id is automatically generated on the server when a user is created.
   603          type: integer
   604          format: int64
   605          readOnly: true
   606        screenName:
   607          title: The screen name for the user.
   608          description: |
   609            This is used for vanity type urls as well as login credentials.
   610          type: string
   611          pattern: \w[\w_-]+
   612          minLength: 3
   613          maxLength: 255
   614        availableKarma:
   615          title: The amount of karma this user has available.
   616          description: |
   617            In this application users get a cerain amount of karma alotted.
   618            This karma can be donated to other users to show appreciation, or it can be used
   619            by a user to vote on issues.
   620            Once an issue is closed or rejected, the user gets his karma back.
   621          type: number
   622          format: float32
   623          maximum: 1000
   624          exclusiveMaximum: true
   625          readOnly: true
   626        admin:
   627          title: When true this user is an admin.
   628          description: |
   629            Only employees of the owning company can be admins.
   630            Admins are like project owners but have access to all the projects in the application.
   631            There aren't many admins, and it's only used for extremly critical issues with the application.
   632          type: boolean
   633          readOnly: true