Swagger is a tool that allows you to design and document REST APIs. Swagger is based
on the OpenAPI specification.
Swagger includes a Swagger Editor tool that you’ll use to
edit your API specification. This tool allows you to export the API specification to either a yaml or json file.
jhDocs includes a jhdocs-swagger-ui shortcode that allows you to display a Swagger API specification file.
This shortcode takes one parameter:
url: The URL of the API specification file
After exporting your API specification to a yaml or json file from the Swagger Editor, you’ll then add that API specification
file into your documentation site.
You’ll then add an instance of the jhdocs-swagger-ui shortcode to a markdown page in your site, setting the shortcode’s
url parameter to the URL within your doc site for the API specification file.
If the url links to a Swagger UI specfile that’s local to your site (versus a remote file in a different site), then the content
within the specfile will be made visible to your site search, allowing users to search your site for content that’s found
within the specfile itself. If you link to a remote specfile, that content is not embedded or searchable within your site.
Configuring Swagger support
Before you can use the jhdocs-swagger-ui shortcode in your content, you must first define a swaggerSupport parameter
with a value of standard in your config.yaml file in order for your Swagger UI
spec files to display properly. This setting tells jhDocs to load the Swagger UI CSS from the version of Swagger UI that
is distributed by jhDocs.
If your site uses a custom Swagger UI setup (to date this is only the
Digital Toolkit doc site), you must first define a
swaggerSupport parameter with a value of custom in your config.yaml file in order
for your Swagger UI spec files to display properly. This setting tells jhDocs to load the Swagger UI CSS from the
node_modules/swagger-ui-dist folder.
Swagger UI in the Digital Toolkit doc site
The Digital Toolkit documentation site uses Swagger UI to document its service APIs,
but has added custom code to set up tight integration with the Garden test environment for authorization. That site
currently uses an older version of swagger-ui, with some complex custom integration.
In contrast, the jhdocs-swagger-ui shortcode described here uses a more recent version of swagger-ui and does not
have custom code that integrates with the Garden test environment. Our goal is to see if this generic Swagger UI shortcode
will serve the needs of our other doc sites without requiring custom integration for authorization.
Swagger and the Table of Contents
Swagger has the unfortunate side effect of interfering with intradocument links (linking to locations within a document
and not just to the document itself) needed for a table of contents, so this shortcode will hide the table of contents
in any page that it’s in.
For this reason, you may want to partition your documentation to avoid mixing complex documentation that needs
headers in the same page as a Swagger specfile. You can of course certainly do that, but the table of contents will
be hidden.
Example
Below, we see the jhdocs-swagger-ui shortcode displaying an API specification. The Authorize feature won’t work in this particular site, but you can still explore the API.
openapi: 3.0.3
info:
version: 0.0.1
title: Abilities
servers:
- url: 'https://banno.com'
tags:
- name: Institution Abilities
- name: User Specific Abilities
paths:
'/a/mobile/api/v0/institutions/{institutionId}/abilities':
get:
tags:
- Institution Abilities
description: >-
Lookup the abilities for the given institution.
parameters:
- in: path
name: institutionId
description: id of the institution
required: true
schema:
$ref: '#/components/schemas/InstitutionId'
responses:
'200':
description: >-
The ability set for the given Institution.
content:
application/json:
schema:
$ref: '#/components/schemas/AbilitiesMap'
'/a/mobile/api/v0/institutions/{institutionId}/users/{userId}/abilities':
get:
tags:
- User Specific Abilities
security:
- clientCredentials: []
description: >
Lookup the abilities for the given user at a given
institution. In the general case, a user's ability set will be
similar (if not identical) to that of the institution
abilities, however this is never guaranteed. Any and all of a
given user's abilities can be overridden such that they are
completely different than the institution level abilities.
The response of this endpoint will represent any overridden abilities with their updated values,
an empty response should be interpreted as the user having all default abilities.
parameters:
- in: path
name: institutionId
description: id of the institution
required: true
schema:
$ref: '#/components/schemas/InstitutionId'
- in: path
name: userId
description: id of the user
required: true
schema:
$ref: '#/components/schemas/UserId'
responses:
'200':
description: >-
The ability set for the given User.
content:
application/json:
schema:
$ref: '#/components/schemas/AbilitiesMap'
'/a/mobile/api/v0/abilities/metadata':
get:
tags:
- Institution Abilities
description: >-
Lookup the metadata for Institution abilities. Because the set
of abilities is large and new abilities will be added over
time, this endpoint allows callers to understand what types
are available, their data type, if they have a default value,
and whether or not they are required, and if the type is an
enumerated value (enum), what the valid members of that type
are.
This value is the same for all institutions.
responses:
'200':
description: >-
The metadata describing Institution abilities.
content:
application/json:
schema:
$ref: '#/components/schemas/AbilitiesMetadataArray'
'/a/mobile/api/v0/abilities/metadata/user':
get:
tags:
- Institution Abilities
description: >-
Lookup the metadata for User abilities. Because the set
of abilities is large and new abilities will be added over
time, this endpoint allows callers to understand what types
are available, their data type, if they have a default value,
and whether or not they are required, and if the type is an
enumerated value (enum), what the valid members of that type
are.
This value is the same for all users. Structurally, it will be
very similar to the metadata for the institution.
responses:
'200':
description: >-
The metadata describing User abilities.
content:
application/json:
schema:
$ref: '#/components/schemas/AbilitiesMetadataArray'
'/a/mobile/api/v0/institutions/{institutionId}/users/{userId}/abilities/update':
put:
tags:
- User Specific Abilities
summary: This endpoint will allow you to configure a subset of available abilities.
parameters:
- in: path
name: institutionId
description: id of the institution
required: true
schema:
$ref: '#/components/schemas/InstitutionId'
- in: path
name: userId
description: id of the user
required: true
schema:
$ref: '#/components/schemas/UserId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateRequest'
responses:
'204':
description: OK
'400':
description: Malformed json, invalid keys/values, no key/values
'404':
description: Not Found
'500':
description: Failure
components:
securitySchemes:
clientCredentials:
type: oauth2
description: OAuth2 using the client credentials flow
flows:
clientCredentials:
tokenUrl: https://banno.com/a/oidc-provider/api/v0/token
scopes: {}
schemas:
UpdateRequest:
type: object
properties:
zelle_enabled:
description: >
values
* `None` - disables Zelle.
* `Send` - the user can send money but not request.
* `Request` - the user can request money *and* send it.
* `Split` - not currently supported.
type: string
enum:
- None
- Send
- Request
- Split
rdc:
type: boolean
bill_pay:
type: boolean
external_transfer_inbound:
type: boolean
external_transfer_outbound:
type: boolean
AbilitiesMap:
description: >-
A map of the column names and their respective Json values
(string -> Json). The set of abilities is a somewhat large,
includes some non-boolean values, and new abilities are added
from time to time. Thus, the precise set of abilities this API
call returns will change over time. Specific abilities
returned by a given API endpoint will not be removed or have
their types change.
type: object
example:
export_transactions_enabled: true
bill_pay_sync: false
pay_an_individual_bill_pay: true
distinct_business_profiles: true
mask_account_numbers: false
full_service_credit_card_payments: false
conversations: true
hide_external_accounts_from_admins: false
manage_recurring_payments: true
separate_bill_pay_accounts: false
account_pscu_meta: true
allow_duplicate_usernames: false
offline_mode_enabled: true
check_image_masking: true
two_fa_phone_validation: false
payee_creation: true
run_requests_concurrently: true
payee_edit_p2p_sms: true
change_email: true
creation_transaction_days: 120
ask_question_on_aggregation_transfer: false
password_management: true
look_up_user_status: true
positive_pay: false
allow_invalid_rdc_accounts: false
view_employee_info_enabled: true
rdc_onboardding_enabled: true
hra_authy_code_web: false
change_phone: true
external_transfer_inbound: true
send_email_to_user_on_event: true
payee_edit: false
check_images_enabled: true
ach: true
bill_pay: true
self_enrollment_individual_only: false
schedulable_transfers: true
recurring_transactions: false
set_user_management: false
alternate_account_transfer_flow: false
allow_ssn_signup: false
filter_rdc_accounts_by_customer_id: false
advanced_card_controls_enabled: false
zelle_enabled: None
enforce_bsl_entitlements: true
documents: true
session_expiration_timeout_minutes: 30
two_fa_enabled: true
member_to_member_transfers: false
add_recurring_payments: true
small_business_wire: true
payment_card_management: false
hra_authy_code_mobile: false
account_to_account: false
user_management: false
travel_notices: false
disable_transfers_for_cash_management_users: false
session_resumption_method: PIN
statement_reports_enabled: false
p2p_enabled: true
external_accounts: true
self_enrollment: true
geezeo_insights: false
payee_deletion: false
account_rewards: false
account_symx_meta: false
switch_user_enabled: true
running_balance: Posted
alerts_enabled: true
usernames_case_sensitive: false
account_pscu_meta_rewards: true
cutoff_time: '1970-02-12T01:00:00Z'
external_transfer_outbound: true
business_bill_pay: true
consumer_external_links_enabled: true
rdc_onboarding_by_accounts_enabled: true
deposit_set: false
rdc: true
change_account_name: true
use_new_display_name: false
small_business_ach: true
mobile_ads_enabled: false
change_address: Conversations
ads_enabled: true
self_recovery: true
bill_pay_enrollment: true
mfa_question_edit: false
wires: true
stop_payments: true
change_username: true
credit_images: true
account_jx_meta: true
AbilitiesMetadataArray:
description: >-
An array of the metadata for abilities. One entry for each ability.
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/AbilitiesMetadata'
AbilitiesMetadata:
description: >-
An object which corrisponds to the Abilities object. It
describes metadata for a given ability.
type: object
example:
name: rdc
optional: false
default:
value: null
dataType: boolean
enumerationValues: []
required:
- name
- optional
- dataType
properties:
name:
description: >-
The name of the ability. This will be the key for the
ability in the Json object returned on the abilities
lookup.
type: string
optional:
description: >-
If true, then this ability may be unset. Structurally,
this is not the same as false (for boolean abilities),
whether or not the semantics are the same as false (for
boolean abilities) varies depending on the ability.
type: boolean
default:
description: >-
The default value for this ability, if it was not set
explicitly for the institution.
Not all abilities have default values.
type: object
dataType:
description: >-
The (JSON) dataType for the ability. Note, certain
abilities may have a more restricted underlying type. For
example, there are a few abilities which are date-time
values. Their JSON type is string, but their valid type is
an ISO 8601/RFC 3339 date-time.
type: string
enum:
- boolean
- instant
- enumeration
- string
- integer
enumerationValues:
description: >-
If the data type is an enumeration, e.g. it has a closed
set of possible values, this will return the possible
values.
type: array
uniqueItems: true
items:
type: string
InstitutionId:
description: id of the institution
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000
UserId:
description: id of the User
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000