Skip to content

Instantly share code, notes, and snippets.

@codfish codfish/swagger.yml
Created Apr 3, 2018

Embed
What would you like to do?
Example swagger 2.0 doc with extensive use of reusable definitions, responses & parameters.
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.