Documentation

How to Use Swagger UI and "Try it Out" in the DHCS Developer Portal

Overview

This guide provides step-by-step instructions for using Swagger UI within the DHCS Developer Portal to explore, understand, and test API endpoints. You'll learn how to navigate the interactive documentation, examine API specifications, and use the "Try it out" feature to execute API requests with mock data directly from your browser.

What Is Swagger UI?

Swagger UI is a free and open source tool that allows you to visualize and interact with an API’s resources. It parses an OpenAPI (formerly “Swagger”) specification file (in JSON or YAML format) and generates an interactive documentation website where users can:

  • View all available API endpoints and their HTTP methods
  • See details for each endpoint’s parameters and request/response models
  • Try out API requests directly from the browser ("Try it out")

Access the Swagger API

The DHCS Developer Portal’s Swagger API has been made ADA compliant and so may appear slightly different from versions you have seen before. However, it is similar enough that you should be able to navigate easily.

Select the API Catalog tab in the navigation bar.

This opens the API Catalog section of the DHCS Developer Portal and lists the APIs available to you.

Access Swagger UI from the API Catalog

Select an API from the list and click on the its associated API tile.

This opens the Swagger UI for the selected API.

The API tile shows the number of versions configured for that API.

Explore the Swagger Documentation

At the top, you will find the API Description (A), including the API version and contact person.

Below that, you can find the API endpoints listed in collapsible sections (B).

For any API endpoint, you can hover over it and click the button to copy its path to the clipboard (C).

View API Details

  1. If available, select the API version from the dropdown (A) at the top of the Swagger API page. This version will control which set of Swagger documentation (e.g., endpoints, schemas) is displayed.
  2. Select any endpoint to view its parameters, request/response details, and structure.

Try it Out - To learn how to access the “Try it Out” feature for this API endpoint, see the Try it Out section below.

Collect the API’s URL

When it comes time to interact with the API, you will need to know the full URL to your endpoints. The schema and host base URL for the API can be found on the API Details page.

You may come back to this page at a later time to retrieve it.

Access “Try it Out” from Swagger UI

Select an API Endpoint

  1. From within the Swagger UI API documentation page (see above), select an endpoint to test with the “Try it out” feature. In this example we’re accessing the “Health” endpoint.
  2. Click the Try it out button at the top right of the expanded section.
    This enables the "Try it out" functionality for that endpoint.

Configure “Try it Out” API Call

  1. Select the response format from the dropdown menu to view different response examples
  2. Click the Execute button to run the API request

To exit out of the “Try it Out” feature, you can use the Cancel button at any time.

Explore the “Try it Out” Response

Mock data generates API responses when testing endpoints. When you execute a request using the Try it Out feature, Swagger UI creates these responses based on the API specification. The quality of these mock responses depends on how detailed the specification is. The most realistic responses appear when detailed schemas are defined, such as in the 200 response for the Health endpoint, which includes specific data types and example values.

Curl
The complete curl command generated for your API request. This command uses the actual API URL and is ready to use from a command line or terminal. The bearer token displays as <REDACTED> for security purposes.

To use this curl command to make a real API call:

  1. Copy the curl command from the Swagger UI response
  2. Replace the redacted token with your actual bearer token
    • If you haven’t already, request access to an API to get your Ping credentials (client_id and client_secret) to generate your JWT token.
    • If you have access, learn how to retrieve your token on the JWT Authentication with an API page.
    • Replace <REDACTED> in the Authorization header with your actual token

Example using the current ‘ESS Multiversion Demo API’:

curl -X 'GET' \
  'https://multiversion-demo-api.gateway.mes.dhcs.ca.gov/api/v2/Health' \
  -H 'accept: application/json' \
  -H 'Access-Control-Allow-Origin: true' \
  -H 'Authorization: Bearer <REDACTED>'

Request URL
The full URL that was called during the API request, including the base URL, endpoint path, and any query parameters.

Server Response
The server response section displays the information returned after executing the request. The response data shown is mock data based on the API specification.

  • Code - The HTTP status code returned by the server (e.g., 200 for “Success”).
  • Response body - The data returned by the API, typically in JSON format. Available formats are shown in the Media Type Selector below.
    Example from the Health endpoint: {"status": "processing", "health": "degraded"}
  • Response headers - Additional metadata sent back by the server, such as content type, encoding information, and other technical details about how the response should be handled.
  • Request duration - The time it took for the API to process and respond to your request, measured in milliseconds (ms).

Responses
Below the Response panel, the Responses documentation section provides detailed information about the API’s expected response structure.

  • **Media Type Selector **

    • This dropdown menu displays the available response content types for the endpoint. Most commonly, this shows application/json, indicating the API returns data in JSON format. If available, select a media type from the dropdown to view its corresponding response format.

  • **Example Value / Schema Toggle **

    • Example Value - Displays a sample response with example data. This shows what an actual API response might look like, including sample values for each field.
    • Schema - Displays the technical specification of the response structure, including:
      • For example, the HealthResponseschema shows:
        • status* (required string field) - “Long description of current status of the service”
        • health (string field) - Enumeration with allowed values: Normal, Degraded, or Unavailable