Over a million developers have joined DZone.

API Views With OpenAPI Spec And Liquid

I have been pushing forward my API documentation, beyond the (now) standard issue Swagger UI, keeping the OpenAPI Spec core, but evolving the UI portion using Jekyll and Liquid.

· Integration Zone

Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.

I just published the OpenAPI Spec I just created for the Human Services Data Specification (HSDS) into one of my default portals, which once the OpenAPI Spec is indexed via the portals API.json, I get a ready to go landing page, documentation, and other tooling for supporting the API. I have been pushing forward my API documentation, beyond the (now) standard issue Swagger UI, keeping the OpenAPI Spec core, but evolving the UI portion using Jekyll and Liquid. 

I have a default API docs implementation, which loops through all OpenAPI Spec included within a project, and renders HTML documentation for each path, verb, etc. I'm still working on how I recreate the dynamic functionality brought to the table by Swagger UI, but so far I'm really, really enjoying the flexibility with the user interface, and overall experience I get using this approach--I know the interactive portion will come.

One of the things I'm enjoying being able to do is apply additional, external elements to the OpenAPI Spec, by augmenting them with independent, APIs.json defined schema. One example of this I am calling API filters, a simple filter collection defined in both YAML and JSON, that is indexed along with the OpenAPI Spec, within the APIs.json index. For the Open Referral API I wanted to provide the complete documentation, but also play around with other different, filtered views of the API—designed for specific audiences.

The first entry I made into API filters, I called "learn the basics", only showing the core resources that were available via the Open Referral API, eliminating all of the noise.

Open Referral API - Learn the BasicsOpenAPI Spec
Get all categories/categoriesGET
Get Contacts/contactsGET
Create New Contact/contactsPOST
Get Locations/locationsGET
Add Location/locationsPOST
Get Metadata/metadataGET
Add New Metadata/metadataPOST
Get Locations/organizationsGET
Create a new organization/organizationsPOST
Get locations that match certain criteria./searchGET
Get Services/servicesGET

Create New Service

This API docs view, gives me just the handful of core endpoints, filtering out the other 60+ APIs that someone who is just learning about the Open Referral API do not need to be bothered with when they are learning. Next, I wanted to focus in on a specific area of the API, like services, and only show the summary elements, that most people will care about when it comes to these services. I'm calling this one "services summary":

Open Referral API - Services SummaryOpenAPI Spec
Get Services/servicesGET
Create New Service/servicesPOST
Service - Categories
Update a service’s categories/services/:service_id/categoriesPUT
Service - Contacts
Get Contacts/services/:service_id/contactsGET
Add Contact/services/:service_id/contactsPOST
Service - Eligibility
Get Eligibility/services/:service_id/eligibility/GET
Add Eligibility/services/:service_id/eligibility/POST
Service - Fees
Get Fees/services/:service_id/fees/GET
Add Fees/services/:service_id/fees/POST
Service - Funding
Get Funding/services/:service_id/funding/GET
Add Funding/services/:service_id/funding/POST
Service - Holiday Schedule
Get Holiday Schedule/services/:service_id/holiday_schedule/GET
Add Holiday Schedule/services/:service_id/holiday_schedule/POST
Service - Interpretation Services
Get Interpretation Services/services/:service_id/intepretation_services/GET
Add Interpretation Services/services/:service_id/intepretation_services/POST
Service - Languages
Get Languages/services/:service_id/languages/GET
Add Languages/services/:service_id/languages/POST
Service - Payment Accepted
Get Payment Accepted/services/:service_id/payment_accepted/GET
Add Payment Accepted/services/:service_id/payment_accepted/POST
Service - Phones
Get Phones/services/:service_id/phonesGET
Add Phone/services/:service_id/phonesPOST
Service - Regular Schedule
Get Regular Schedule/services/:service_id/regular_scheduleGET
Add Regular Schedule/services/:service_id/regular_schedulePOST
Service - Required Document
Get Required Document/services/:service_id/required_document/GET
Add Required Document/services/:service_id/required_document/POST
Service - Areas
Get Service Area/services/:service_id/service_area/GET
Add Service Area/services/:service_id/service_area/


The Liquid driven HTML API docs are the same for the full documentation, for learn the basics, or for the services summary. All three documentation elements are also all driven from the same OpenAPI Spec. The only thing I did, was specify one of the API Filters by name, in the top of each specialized docs page -- the Liquid template handles the rest. Its still pretty crude, and I'm sure it will need a lot of polishing, but it provides me with a simple, machine readable way to filter out the endpoints I do not need, accomplishing what I set out to do.

- name: Learn the Basics
- path: /categories
- path: /contacts
- path: /locations
- path: /metadata
- path: /organizations
- path: /search
- path: /services
- name: Services Summary
- path: /services
- path: /services/:service_id/categories
- path: /services/:service_id/contacts
- path: /services/:service_id/eligibility/
- path: /services/:service_id/fees/
- path: /services/:service_id/funding/
- path: /services/:service_id/holiday_schedule/
- path: /services/:service_id/intepretation_services/
- path: /services/:service_id/languages/
- path: /services/:service_id/payment_accepted/
- path: /services/:service_id/phones
- path: /services/:service_id/regular_schedule
- path: /services/:service_id/required_document/

- path: /services/:service_id/service_area/

I am using schema approaches like this more lately. An approach that when indexed along with the OpenAPI Spec, in an API.json file gives me other layers, and dimension that I can apply for not just documentation, but almost any other stop along the life cycle. To me, and important part of this is that these elements do not live embedded within the OpenAPI Spec, living independent of the the machine readable definition of the API. Each one lives its own schema file, and when indexed alongside each API definition, within the APIs.json, interesting things happen--all without cluttering up the OpenAPI Spec, keeping it purely about the API.

My goal in this work, is to provide me with a way that I can equip the other less technical advocates for the Open Referral format, with a toolbox of documentation, visualizations, and other snippets that will help them articulate what the API can do. Since all of these API documentation snippets are APIs.json, and OpenAPI Spec driven, using Liquid, and Jekyll to render, they are something that anyone could put to use, for any API.

The Integration Zone is brought to you in partnership with CA Technologies.  Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.


Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}