github.com/kaisawind/go-swagger@v0.19.0/fixtures/codegen/tasklist.basic.yml (about)

     1  swagger: '2.0'
     2  host: localhost:8322
     3  basePath: /v1
     4  schemes:
     5    - http
     6    - https
     7  produces:
     8    - application/json
     9  consumes:
    10    - application/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://github.com/go-swagger
    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    Currency:
   374      type: string
   375      enum:
   376        - EUR
   377        - GBP
   378        - JPY
   379        - USD
   380  
   381    Price:
   382      type: object
   383      properties:
   384        amount:
   385          type: integer
   386          format: int32
   387        currency:
   388          $ref: "#/definitions/Currency"
   389  
   390    TaskCard:
   391      title: a card for a task
   392      description: |
   393        A task card is a minimalistic representation of a task. Useful for display in list views, like a card list.
   394      type: object
   395      required:
   396        - title
   397        - status
   398      properties:
   399        id:
   400          title: The id of the task.
   401          description: A unique identifier for the task. These are created in ascending order.
   402          type: integer
   403          format: int64
   404          readOnly: true
   405        title:
   406          title: The title of the task.
   407          description: |
   408            The title for a task, this needs to be at least 5 chars long.
   409            Titles don't allow any formatting, besides emoji.
   410          type: string
   411          minLength: 5
   412          maxLength: 150
   413        description:
   414          title: The description of the task.
   415          description: |
   416            The task description is a longer, more detailed description of the issue.
   417            Perhaps it even mentions steps to reproduce.
   418          type: string
   419        milestone:
   420          $ref: "#/definitions/Milestone"
   421        severity:
   422          type: integer
   423          format: int32
   424          minimum: 1
   425          maximum: 5
   426        effort:
   427          description: the level of effort required to get this task completed
   428          type: integer
   429          format: int32
   430          maximum: 27
   431          multipleOf: 3
   432        karma:
   433          title: the karma donated to this item.
   434          description: |
   435            Karma is a lot like voting.  Users can donate a certain amount or karma to an issue.
   436            This is used to determine the weight users place on an issue. Not that +1 comments aren't great.
   437          type: number
   438          format: float32
   439          minimum: 0
   440          exclusiveMinimum: true
   441          multipleOf: 0.5
   442        status:
   443          title: the status of the issue
   444          description: |
   445            There are 4 possible values for a status.
   446            Ignored means as much as accepted but not now, perhaps later.
   447          type: string
   448          enum: ["open", "closed", "ignored", "rejected"]
   449        assignedTo:
   450          $ref: "#/definitions/UserCard"
   451        reportedAt:
   452          title: The time at which this issue was reported.
   453          description: |
   454            This field is read-only, so it's only sent as part of the response.
   455          type: string
   456          format: date-time
   457          readOnly: true
   458        tags:
   459          title: task tags.
   460          description: a task can be tagged with text blurbs.
   461          type: array
   462          uniqueItems: true
   463          maxItems: 5
   464          items:
   465            pattern: \w[\w- ]+
   466            minLength: 3
   467            type: string
   468  
   469    Task:
   470      title: a structure describing a complete task.
   471      description: |
   472        A Task is the main entity in this application. Everything revolves around tasks and managing them.
   473      type: "object"
   474      allOf:
   475        - $ref: "#/definitions/TaskCard"
   476        - type: object
   477          properties:
   478            lastUpdated:
   479              title: The time at which this issue was last updated.
   480              description: |
   481                This field is read only so it's only sent as part of the response.
   482              type: string
   483              format: date-time
   484              readOnly: true
   485            reportedBy:
   486              $ref: "#/definitions/UserCard"
   487            lastUpdatedBy:
   488              $ref: "#/definitions/UserCard"
   489            comments:
   490              title: The 5 most recent items for this issue.
   491              description: |
   492                The detail view of an issue includes the 5 most recent comments.
   493                This field is read only, comments are added through a separate process.
   494              readOnly: true
   495              type: array
   496              items:
   497                $ref: "#/definitions/Comment"
   498            attachments:
   499              title: The attached files.
   500              description: |
   501                An issue can have at most 20 files attached to it.
   502              type: object
   503              additionalProperties:
   504                type: object
   505                maxProperties: 20
   506                properties:
   507                  name:
   508                    title: The name of the file.
   509                    description: |
   510                      This name is inferred from the upload request.
   511                    type: string
   512                    readOnly: true
   513                  description:
   514                    title: Extra information to attach to the file.
   515                    description: |
   516                      This is a free form text field with support for github flavored markdown.
   517                    type: string
   518                    minLength: 3
   519                  url:
   520                    title: The url to download or view the file.
   521                    description: |
   522                      This URL is generated on the server, based on where it was able to store the file when it was uploaded.
   523                    type: string
   524                    format: uri
   525                    readOnly: true
   526                  contentType:
   527                    title: The content type of the file.
   528                    description: |
   529                      The content type of the file is inferred from the upload request.
   530                    type: string
   531                    readOnly: true
   532                  size:
   533                    title: The file size in bytes.
   534                    description: This property was generated during the upload request of the file.
   535                    type: number
   536                    format: float64
   537                    readOnly: true
   538    Milestone:
   539      title: A milestone is a particular goal that is important to the project for this issue tracker.
   540      description: |
   541        Milestones can have a escription and due date.
   542        This can be useful for filters and such.
   543      type: object
   544      required:
   545        - name
   546      properties:
   547        name:
   548          title: The name of the milestone.
   549          description: |
   550            Each milestone should get a unique name.
   551          type: string
   552          pattern: "[A-Za-z][\\w- ]+"
   553          minLength: 3
   554          maxLength: 50
   555        description:
   556          type: string
   557          title: The description of the milestone.
   558          description: |
   559            A description is a free text field that allows for a more detailed explanation of what the milestone is trying to achieve.
   560        dueDate:
   561          title: An optional due date for this milestone.
   562          description: |
   563            This property is optional, but when present it lets people know when they can expect this milestone to be completed.
   564          type: string
   565          format: date
   566        stats:
   567          title: Some counters for this milestone.
   568          description: |
   569            This object contains counts for the remaining open issues and the amount of issues that have been closed.
   570          type: object
   571          properties:
   572            open:
   573              title: The remaining open issues.
   574              type: integer
   575              format: int32
   576            closed:
   577              title: The closed issues.
   578              type: integer
   579              format: int32
   580            total:
   581              title: The total number of issues for this milestone.
   582              type: integer
   583              format: int32
   584    Comment:
   585      title: A comment for an issue.
   586      description: |
   587        Users can comment on issues to discuss plans for resolution etc.
   588      type: object
   589      required:
   590        - user
   591        - content
   592      properties:
   593        user:
   594          $ref: "#/definitions/UserCard"
   595        content:
   596          title: The content of the comment.
   597          description: |
   598            This is a free text field with support for github flavored markdown.
   599          type: string
   600        createdAt:
   601          title: The time at which this comment was created.
   602          description: This field is autogenerated when the content is posted.
   603          type: string
   604          format: date-time
   605          readOnly: true
   606  
   607    UserCard:
   608      title: A minimal representation of a user.
   609      description: |
   610        This representation of a user is mainly meant for inclusion in other models, or for list views.
   611      type: object
   612      required:
   613        - id
   614        - screenName
   615      properties:
   616        id:
   617          title: A unique identifier for a user.
   618          description: |
   619            This id is automatically generated on the server when a user is created.
   620          type: integer
   621          format: int64
   622          readOnly: true
   623        screenName:
   624          title: The screen name for the user.
   625          description: |
   626            This is used for vanity type urls as well as login credentials.
   627          type: string
   628          pattern: \w[\w_-]+
   629          minLength: 3
   630          maxLength: 255
   631        availableKarma:
   632          title: The amount of karma this user has available.
   633          description: |
   634            In this application users get a cerain amount of karma alotted.
   635            This karma can be donated to other users to show appreciation, or it can be used
   636            by a user to vote on issues.
   637            Once an issue is closed or rejected, the user gets his karma back.
   638          type: number
   639          format: float32
   640          maximum: 1000
   641          exclusiveMaximum: true
   642          readOnly: true
   643        admin:
   644          title: When true this user is an admin.
   645          description: |
   646            Only employees of the owning company can be admins.
   647            Admins are like project owners but have access to all the projects in the application.
   648            There aren't many admins, and it's only used for extremly critical issues with the application.
   649          type: boolean
   650          readOnly: true