Example swagger 2.0 doc with extensive use of reusable definitions, responses & parameters.

swagger.yml

swagger: '2.0'

info:
  version: '0.0.1'
  title: Marketing Campaign API

host: api.example.com

basePath: /v1

schemes:
  - https

consumes:
  - application/json

produces:
  - application/json

tags:
  - name: Campaigns
  - name: Segments
  - name: Field Options
  - name: Counts

paths:
  /campaigns:
    get:
      description: Returns an **array** of campaign objects. **Only campaigns that the requesting user has access too will be returned**.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/parameters/fields'
        - $ref: '#/parameters/count'
        - $ref: '#/parameters/per_page'
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/sort'
      responses:
        200:
          description: Success
          headers:
            Status:
              description: 200 OK
              type: string
            Total-Count:
              description: Total number of campaigns returned in your query. Note that the count represents the total amount of available results, not the amount returned as part of the current response. **IMPORTANT - This header should only be returned when the request was sent with the `count=true` query paramter.**
              type: integer
              format: int32
          schema:
            type: array
            items:
              allOf:
                - $ref: "#/definitions/campaign"
                # overwrite segments property for collection endpoint to only
                # contain references to segment ids, rather than nested objects
                - properties:
                    segments:
                      type: array
                      description: List of related segment ids.
                      items:
                        type: integer
                        format: uuid
                        example: d290f1ee-6c54-4b01-90e6-d701748f0851
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    post:
      description: Creates a campaign and returns the new entity in its entirety.
      tags:
        - Campaigns
      parameters:
        - in: body
          name: campaign
          description: The campaign to create. Below is an example of the request body you should send along.
          required: true
          schema:
            $ref: '#/definitions/campaign'
      responses:
        201:
          description: Created
          headers:
            Status:
              description: 201 Created
              type: string
            Location:
              description: https://api.example.com/v1/campaigns/d290f1ee-6c54-4b01-90e6-d701748f0851
              type: string
              format: url
          schema:
            $ref: '#/definitions/campaign'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
  /campaigns/{id}:
    x-swagger-router-controller: campaigns
    get:
      description: Returns a campaign
      tags:
        - Campaigns
      parameters:
        - $ref: '#/parameters/campaign-id'
      responses:
        200:
          description: Success
          schema:
            $ref: '#/definitions/campaign'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        404:
          $ref: '#/responses/404'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    put:
      description: Replaces a campaign in it's entirety with new data.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/parameters/campaign-id'
        - in: body
          name: campaign
          description: The campaign data to update. Below is an example of the request body you should send along.
          required: true
          schema:
            $ref: '#/definitions/campaign'
      responses:
        200:
          description: Success
          headers:
            Status:
              description: 200 OK
              type: string
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        404:
          $ref: '#/responses/404'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    patch:
      description: Partially updates a campaign with whatever fields are sent in the request.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/parameters/campaign-id'
        - in: body
          name: campaign
          description: The campaign data to update. Below is an example of the request body you should send along. **NOTE** - You can send as little as one field in a PATCH request.
          required: true
          schema:
            $ref: '#/definitions/campaign'
      responses:
        200:
          description: Success
          headers:
            Status:
              description: 200 OK
              type: string
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
  /campaigns/{id}/segments:
    x-swagger-router-controller: campaigns
    get:
      description: Returns a list of segments for a campaign.
      tags:
        - Segments
      parameters:
        - $ref: '#/parameters/campaign-id'
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/segment'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    post:
      description: Creates a segment associated to the campaign and returns the new segment in the response body in its entirety.
      tags:
        - Segments
      parameters:
        - $ref: '#/parameters/campaign-id'
        - in: body
          name: segment
          description: The campaign to create. Below is an example of the request body you should send along.
          required: true
          schema:
            $ref: '#/definitions/segment'
      responses:
        201:
          description: Created
          headers:
            Status:
              description: 201 Created
              type: string
            Location:
              description: https://api.example.com/v1/campaigns/d290f1ee-6c54-4b01-90e6-d701748f0851/segments/9b321c73-bbe5-4a37-9317-d3f1647c1ec2
              type: string
              format: url
          schema:
            $ref: '#/definitions/segment'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
  /campaigns/{id}/segments/{segment-id}:
    x-swagger-router-controller: campaigns
    get:
      description: Returns a single segment for a campaign.
      tags:
        - Segments
      parameters:
        - $ref: '#/parameters/campaign-id'
        - $ref: '#/parameters/segment-id'
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/segment'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    put:
      description: Replaces a campaign's segment in it’s entirety with new data.
      tags:
        - Segments
      parameters:
        - $ref: '#/parameters/campaign-id'
        - $ref: '#/parameters/segment-id'
        - in: body
          name: segment
          description: The campaign segment to create. Below is an example of the request body you should send along.
          required: true
          schema:
            $ref: '#/definitions/segment'
      responses:
        201:
          description: Created
          headers:
            Status:
              description: 201 Created
              type: string
            Location:
              description: https://api.example.com/v1/campaigns/d290f1ee-6c54-4b01-90e6-d701748f0851/segments/9b321c73-bbe5-4a37-9317-d3f1647c1ec2
              type: string
              format: url
          schema:
            $ref: '#/definitions/segment'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
    patch:
      description: Partially updates a campaign segment with whatever fields are sent in the request.
      tags:
        - Segments
      parameters:
        - $ref: '#/parameters/campaign-id'
        - $ref: '#/parameters/segment-id'
        - in: body
          name: segment
          description: The campaign to create. Below is an example of the request body you should send along. **NOTE** - You can send as little as one field in a PATCH request.
          required: true
          schema:
            $ref: '#/definitions/segment'
      responses:
        201:
          description: Created
          headers:
            Status:
              description: 201 Created
              type: string
            Location:
              description: https://api.example.com/v1/campaigns/d290f1ee-6c54-4b01-90e6-d701748f0851/segments/9b321c73-bbe5-4a37-9317-d3f1647c1ec2
              type: string
              format: url
          schema:
            $ref: '#/definitions/segment'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        422:
          $ref: '#/responses/422'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
  /field-options:
    x-swagger-router-controller: options
    get:
      description: Returns a collection of field options to populate form fields.
      tags:
        - Field Options
      parameters:
        - $ref: '#/parameters/count'
        - $ref: '#/parameters/per_page'
        - $ref: '#/parameters/page'
        - name: name
          in: query
          required: false
          type: string
          description: Filter results by `name`. **Example** - `/v1/field-options?name=age_range`
      responses:
        200:
          description: Success
          schema:
            type: array
            items:
              allOf:
                - $ref: "#/definitions/fieldOption"
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'
  /campaigns/{id}/counts:
    x-swagger-router-controller: campaigns
    get:
      description: Returns a breakdown of all of the campaign current counts.
      tags:
        - Counts
      parameters:
        - $ref: '#/parameters/campaign-id'
      responses:
        200:
          description: Success
          schema:
            $ref: "#/definitions/campaignCounts"
        401:
          $ref: '#/responses/401'
        415:
          $ref: '#/responses/415'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/error'

definitions:
  campaign:
    required:
      - name
      - description
      - channel
      - target_deployment_date
      - recipient_selection
    properties:
      id:
        type: string
        format: uuid
        readOnly: true
        example: b646ad6e-f256-44d4-9218-3d77d3b0cff6
      name:
        type: string
        description: Campaign name.
      description:
        type: string
        description: Campaign description.
      target_deployment_date:
        type: string
        format: date
        description: Target campaign deployment date (no time needed?).
        example: "2018-03-13"
      channel:
        type: string
        description: Campaign type.
        enum:
          - postal
          - email
      recipient_selection:
        type: string
        description: Recipient selection.
        enum:
          - household
      service_line:
        type: string
        description: Service line
      viewable_by:
        type: string
        description: Who has access to view/edit this campaign.
        enum:
          - individual
          - public
      refinements:
        type: array
        items:
          $ref: '#/definitions/refinement'
      current_count:
        type: integer
        format: int32
        description: Current total campaign count.
        readOnly: true
        example: 67514
      created_by:
        type: string
        format: uuid
        readOnly: true
        description: User's id
        example: b646ad6e-f256-44d4-9218-3d77d3b0cff6
      segments_url:
        type: string
        format: url
        description: API endpoint to access segments for this campaign.
        example: https://api.example.com/v1/campaigns/b646ad6e-f256-44d4-9218-3d77d3b0cff6/segments
        readOnly: true
      segments:
        type: array
        description: List of related segments.
        readOnly: true
        items:
          $ref: '#/definitions/segment'
  segment:
    required:
      - name
      - description
      - target_individual
    properties:
      id:
        type: string
        format: uuid
        readOnly: true
        example: b646ad6e-f256-44d4-9218-3d77d3b0cff6
      name:
        type: string
        description: Segment name.
      description:
        type: string
        description: Segment description.
      target_individual:
        type: array
        description: Types of individuals to target
        example:
          - patients
          - customers
        items:
          type: string
          enum:
            - patients
            - customers
            - prospects
      gender:
        type: array
        description: Genders to target
        example:
          - male
          - female
        items:
          type: string
          enum:
            - male
            - female
      race:
        type: array
        description: Races to target
        example:
          - white
          - black
        items:
          type: string
          enum:
            - white
            - black
            - hispanic
            - asian
      channel:
        type: array
        description: Segment channels
        example:
          - email
          - postal
        items:
          type: string
          enum:
            - postal
            - email
      refinements:
        type: array
        description: List of segment refinements, aka "Lists, Recipes & Behaviors."
        items:
          $ref: '#/definitions/refinement'
      age_range:
        type: array
        description: List of segment target age ranges.
        items:
          type: string
          example: 70-79
      geography:
        type: array
        description: List of targeted locations.
        items:
          $ref: '#/definitions/location'
      current_count:
        type: integer
        format: int32
        description: Current total segment count.
        readOnly: true
        example: 67514
      created_at:
        type: string
        format: date-time
        description: An ISO-8601 format datetime string. Should get set automatically when a campaign is created, and never change after that.
        readOnly: true
        example: '2017-12-15T09:12:33.001Z'
      modified_at:
        type: string
        format: date-time
        description: An ISO-8601 format datetime string. Should get set automatically set every time a campaign is created or updated.
        readOnly: true
        example: '2017-12-15T09:12:33.001Z'
  refinement:
    description: Suppression or inclusion
    type: object
    properties:
      id:
        type: string
        format: uuid
      type:
        type: string
        enum:
          - suppressed
          - included
  location:
    description: Segment location object.
    type: object
    properties:
      zip:
        type: string
        format: us postal zip code
        example: 11378
      current_count:
        type: integer
        format: int32
        description: Current total location count.
        readOnly: true
        example: 7514
      type:
        type: string
        enum:
          - suppressed
          - included
  fieldOption:
    description: UI field option. Any field that will be populated dynamically will need to have **ALL** of it's options returned via this endpoint (an exception would be campaign suppressions).
    type: object
    properties:
      name:
        type: string
        description: What will be used in the HTML field's name property. `https://www.w3schools.com/tags/att_input_name.asp`
        enum:
          - age_range
          - gender
      value:
        type: string
        description: HTML field value
        example: 70-79
      text:
        type: string
        example: 70-79
  campaignCounts:
    description: Breakdown of campaign counts
    type: object
    properties:
      total_count:
        type: string
        description: Total count for the entire campaign
        example: 67514
      segments:
        type: array
        items:
          $ref: '#/definitions/segmentCounts'
  segmentCounts:
    description: Breakdown of segment counts
    type: object
    properties:
      id:
        type: string
        format: uuid
        example: 9b321c73-bbe5-4a37-9317-d3f1647c1ec2
      total_count:
        type: string
        description: Total count for the entire campaign
        example: 67514
      patients_count:
        type: integer
        format: int32
        example: 20426
      customers_count:
        type: integer
        format: int32
        example: 7032
      prospects_count:
        type: integer
        format: int32
        example: 40056
  validationError:
    description: Validation error response body.
    type: object
    properties:
      message:
        type: string
        description: Error message
        example: Validation failed.
      errors:
        type: array
        description: Field errors
        items:
          type: object
          properties:
            field:
              type: string
              example: target_deployment_date
            message:
              type: string
              example: Target Deployment Date is required
  error:
    description: Basic error response body
    type: object
    properties:
      message:
        type: string
        description: Error message
        example: Sample error message text

responses:
  400:
    description: Bad Request
    examples:
      Malformed request body:
        message: Body should be a valid JSON object
    headers:
      Status:
        description: 400 Bad Request
        type: string
    schema:
      $ref: '#/definitions/error'
  401:
    description: Unauthorized
    examples:
      application/json:
        message: You're not authorized to access this item
    headers:
      Status:
        description: 401 Unauthorized
        type: string
    schema:
      $ref: '#/definitions/error'
  404:
    description: Entity not found
    examples:
      application/json:
        message: Campaign could not be found
    headers:
      Status:
        description: 404 Not Found
        type: string
    schema:
      $ref: '#/definitions/error'
  415:
    description: Unsupported Media Type
    examples:
      application/json:
        message: The API refuses to accept the request because the payload format is in an unsupported format. The format problem might be due to the request's indicated `Content-Type` or `Content-Encoding`, or as a result of inspecting the data directly.
    headers:
      Status:
        description: 415 Unsupported Media Type
        type: string
    schema:
      $ref: '#/definitions/error'
  422:
    description: Unprocessable Entity
    headers:
      Status:
        description: 422 Unprocessable Entity
        type: string
    schema:
      $ref: '#/definitions/validationError'
  500:
    description: Internal Server Error
    headers:
      Status:
        description: 500 Internal Server Error
        type: string
    schema:
      $ref: '#/definitions/error'
  error:
    description: Unexpected error
    schema:
      $ref: '#/definitions/error'

parameters:
  campaign-id:
    name: id
    type: string
    format: uuid
    in: path
    description: Campaign ID
    required: true
  segment-id:
    name: segment-id
    type: string
    format: uuid
    in: path
    description: Segment ID
    required: true
  count:
    name: count
    type: boolean
    in: query
    description: Whether or not to return the total count of the request results as a header.
    required: false
  fields:
    name: fields
    type: string
    in: query
    description: Comma delimited list of fields to return for each resource.
      `?fields=name,description,channel,service_line,total_count,viewable_by`
    required: false
  sort:
    name: sort
    type: string
    in: query
    description: Field to sort by. Prefix with `-` to sort descending. i.e. `sort=modified_by` or `sort=-name`
    required: false
  per_page:
    name: per_page
    type: integer
    format: int32
    in: query
    description: Number of items to retrieve. Default is 30, maximum is 100.
    required: false
  page:
    name: page
    in: query
    type: integer
    format: int32
    description: Offset the list of returned results by this amount. Default is zero.