Happy Business Starts Here

How to include custom fields in Swagger

Zuora Documentation

How to include custom fields in Swagger

This post explains how to include custom fields in a copy of the Zuora Swagger spec (also known as the Zuora OpenAPI spec). This would be a useful thing to do if you are generating code from our Swagger spec.


In our Swagger spec, there is a model that represents the custom fields of each type of object. For example, the model for custom fields of Rate Plan objects is called RatePlanObjectCustomFields. This model is referenced in all the places that Rate Plan custom fields are supported in the REST API, so you only have to change this one part of the Swagger spec if you want to include your Rate Plan custom fields.


Rather than modifying the Swagger spec by hand, it would be better to write a script that makes the desired changes. The following JavaScript example loads the Swagger spec, inserts a Rate Plan custom field called customField__c of type string, then outputs the modified Swagger spec.


const fs = require("fs");
const loadYAML = require("js-yaml").load;

// Load the Swagger spec from a YAML file
var specYAML = fs.readFileSync("swagger.yaml", "utf8");
var spec = loadYAML(specYAML);

// Define a JSON schema for Rate Plan custom fields
var ratePlanCustomFields = {
  type: "object",
  properties: {
    customField__c: {
      type: "string",
      description: "A custom field."

// Insert Rate Plan custom fields into the Swagger spec
spec.definitions.RatePlanObjectCustomFields = ratePlanCustomFields;

// Output the modified Swagger spec as a JSON file
var specJSON = JSON.stringify(spec, null, 2);
fs.writeFileSync("swagger-custom.json", specJSON, "utf8");


This script is intended to be run using Node.js. You can use it as a starting point for your own script.


If you have any questions or comments about this approach to including custom fields in our Swagger spec, please post them below!


See this article in the Knowledge Center for general information about custom fields in Zuora: https://knowledgecenter.zuora.com/BB_Introducing_Z_Business/Manage_Custom_Fields

Tags (1)