description: Third line of address — for example, Wellington

example: Wellington

address4:

type: string

country:

type: string

description: This is a human readable country name — for example, New Zealand and not

a country code

example: New Zealand

_links:

type: array

readOnly: true

description: An array of related links relevant to the request/response.

items:

properties:

rel:

type: string

description: A piece of information providing context for the link — for example,

self or accounts.

href:

type: string

description: A fully qualified URL to the resource.

errorModel:

type: object

properties:

errors:

type: array

items:

description: An array of error items containing error codes and descriptions.

Note that the error descriptions will be normalised.

properties:

code:

type: integer

format: int32

description: An error code — should be used in conjunction with the HTPP

response code.

description:

type: string

description: A short description of the error.

_links:

type: array

items:

properties:

rel:

type: string

description: The relationship to the request — for example,. self that contains the

resource that was requested or {object name}, a link to a

resource that is related to the requested resource

href:

type: string

description: A link to the related resource. In an error scenario this is

likely to be something such as a link to a support portal.

_links:

type: array

items:

properties:

rel:

type: string

description: The relationship to the request — for example, self that contains the

resource that was requested or {object name}, a link to a resource

that is related to the requested resource

href:

type: string

description: A link to the related resource

Swagger 2.0 example

#Example API Specification for Agency X

#Author Swithin Foote Middleware New Zealand

swagger: '2.0'

info:

version: 2.0.0

title: Example Agency API

description: A sample API specification demonstrating OpenAPI capabilities — this is for example purposes only

termsOfService: https://developer.example.govt.nz/termsandconditions/

contact:

name: Example Agency API team

email: exampleteam@api.govt.nz

url: https://agency.govt.nz

host: api.example.govt.nz

basePath: /v2

paths:

/customers/{customerId}:

get:

parameters:

\- name: customerId

in: path

description: Unique ID of customer

required: true

type: string

tags:

\- get customer details

description: |

Returns details for a customer given a unique customer ID

security:

\- AuthorizationCode:

\- customerRead

produces:

\- application/json

responses:

200:

description: OK - Successful

schema:

$ref: '#/definitions/customerDetailsResponse'

default:

description: Error response

schema:

$ref: '#/definitions/errorModel'

put:

tags:

\- modify customer

description: Updates a customer’s details

consumes:

\- application/json

produces:

\- application/json

parameters:

\- name: customerId

in: path

description: Unique ID of customer

required: true

type: string

\- name: body

in: body

required: true

schema:

$ref: "#/definitions/customerRequestModel"

responses:

200:

description: Updated resource successfully

default:

description: Error response

schema:

$ref: '#/definitions/errorModel'

security:

\- AuthorizationCode:

\- customerWrite

delete:

tags:

\- delete customer

description: Deletes an existing customer resource

consumes:

\- application/json

produces:

\- application/json

parameters:

\- name: customerId

in: path

description: Unique ID of customer

required: true

type: string

responses:

200:

description: Deleted resource successfully

default:

description: Error response

schema:

$ref: '#/definitions/errorModel'

security:

\- AuthorizationCode:

\- customerDelete

/customers:

post:

tags:

\- create customer

description: Creates a new customer. API will create a customer resource and, if successful, return a hyperlink to the created resource

consumes:

\- application/json

produces:

\- application/json

parameters:

\- name: body

in: body

required: true

schema:

$ref: "#/definitions/customerRequestModel"

responses:

201:

description: Created resource successfully

schema:

$ref: '#/definitions/_links'

default:

description: Error response

schema:

$ref: '#/definitions/errorModel'

security:

\- AuthorizationCode:

\- customerCreate

securityDefinitions:

AuthorizationCode:

type: oauth2

scopes:

customerRead: Grants read access to a customer resource

customerWrite: Grants write (update) access to an existing customer resource

customerCreate: Grants access to create a new customer resource

customerDelete: Grants access to delete an existing customer resource

flow: accessCode

authorizationUrl: https://idm.example.govt.nz/oauth/authorize

tokenUrl: https://idm.example.govt.nz/oauth/access_token

definitions:

customerRequestModel:

type: object

properties:

names:

type: object

properties:

firstName:

type: string

description: Customers first name

middleName:

type: string

description: Customers middle name

lastName:

type: string

description: Customers last name

salutation:

type: string

description: Customers salutation — for example, Mr John Doe

title:

type: string

description: Customers title — for example,. Ms, Mr, Mrs, Dr, and so on.

addresses:

type: array

description: An array of addresses. Unpopulated properties or items will be returned as null JSON objects.

items:

properties:

addressType:

type: string

description: Address type — for example, Home, Business

address1:

type: string

description: First line of the address — for example, 2 something street

address2:

type: string

description: Second line of address — for example, Khandallah

address3:

type: string

description: Third line of address — for example, Wellington

address4:

type: string

country:

type: string

description: This is a human readable country name — for example,. New Zealand and not a country code

customerDetailsResponse:

type: object

required:

\- customerId

properties:

customerId:

type: string

description: Unique identifier for the customer resource — GUID format

names:

type: object

properties:

firstName:

type: string

description: Customers first name

middleName:

type: string

description: Customers middle name

lastName:

type: string

description: Customers last name

salutation:

type: string

description: Customers salutation — for example, Mr John Doe

title:

type: string

description: Customers title — for example, Ms, Mr, Mrs, Dr, and so on.

addresses:

type: array

description: An array of addresses. Unpopulated properties or items will be returned as null JSON objects.

items:

properties:

addressType:

type: string

description: Address type — for example, Home, Business

address1:

type: string

description: First line of the address — for example, 2 something street

address2:

type: string

description: Second line of address — for example, Khandallah

address3:

type: string

description: Third line of address — for example, Wellington

address4:

type: string

country:

type: string

description: This is a human readable country name — for example, New Zealand and not a country code

_links:

type: array

description: An array of related links relevant to the request/response.

items:

properties:

rel:

type: string

description: A piece of information providing context for the link — for example, self or accounts.

href:

type: string

description: A fully qualified URL to the resource.

errorModel:

type: object

properties:

errors:

type: array

items:

description: An array of error items containing error codes and descriptions. Note that the error descriptions will be normalised.

properties:

code:

type: integer

format: int32

description: An error code — should be used in conjunction with the HTPP response code.

description:

type: string

description: A short description of the error.

_links:

type: array

items:

properties:

rel: