Sending Data to Your Documentation's Users

Basic Format

📘

We Accept JSON!

ReadMe's API, OAuth, JWT, and Personalized Docs Webhook consume JSON.

By sending a specific format, you can describe your user to ReadMe and embed information about them directly in your documentation. Any data that is passed can be used as a variable.

An example user object is defined below:

{
  "name": "Owlbert",
  "email": "[email protected]",
  "apiKey": "12345",
  "parameters": {
    "x-readme-version": "1.0",
    "slug": "getting-started"
  }
}

{
  "name": "Owlbert",
  "email": "[email protected]",
  "isAdmin": true,
  "keys": [
    {
      "apiKey": "12345",
      "name": "Enterprise API Key"
    },
    {
      "apiKey": "678910",
      "name": "Personal API Key"
    }
  ],
  "allowedProjects": ["parent-project", "child-project"]
}

{
  "name": "Owlbert",
  "email": "[email protected]",
  "keys": [
    {
      "apiKey": "12345",
      "name": "Enterprise API Key"
    },
    {
      "apiKey": "678910",
      "name": "Personal API Key"
    }
  ],
  "allowedProjects": [
    { "subdomain": "child-project", "access": "readonly" },
    { "subdomain": "child-project-2", "access": "admin" }
  ]
}

ReadMe-Specific Variables

While you can define any variable within your documentation, certain variables have specific meaning within ReadMe.

Referencing Variables in Documentation

The data passed in can be used as variables in the documentation. Just wrap the variable name with <<${variable}>> to user's value, or the default if no value is set. For example, using the above payload, <<name>> will be replaced with "Owlbert" in your documentation.

Defining Defaults in the API Reference

By adding the parameters object in the user object, you'll be able to pre-populate parameters on endpoints. Let's consider the following user object:

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "parameters": {
    "x-readme-version": "1.0",
    "slug": "getting-started"
  }
}

When the logged-in user with the above user data payload visits an endpoint in the API Reference section that has parameters with the IDs x-readme-version or slug present, for example, our Get Doc endpoint, the parameters will be pre-filled with the values defined.

🚧

Single Project Support

Auto-populating parameters currently only works for single-project. It will not work if the parameters object is added within the keys array.

Using Variables with your API

By setting specific variables in your user object, authentication fields will automatically use those values when a user logs in.

OAuth and API Key Authentication

If apiKey is set in the passed in JSON object (like in the following example) and the API Reference section is using OAuth or API Key Authentication, the value will automatically be set.

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "apiKey": "12345"
}

Basic Auth

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "isAdmin": true, // Optional
  "user": "user",
  "pass": "pass"
}

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "isAdmin": true, // Optional
  "keys": [
    {
      "user": "Marc 1",
      "pass": "Pass 1",
      "name": "Marc's 1st Project"
    }, 
    {
      "user": "Marc 2",
      "pass": "Pass 2",
      "name": "Marc's 2nd Project"
    }
  ]
}

If the user object looks like this example, and the authentication is set to Basic Auth, the values will be automatically set the user and pass.

Multiple security schemes

As an alternative to the above, you can also pass in values to the user object that have the same name as your OAS Security Schemes. So for the following securitySchemes:

{
  "oauth2Scheme": {
    "type": "oauth2"
  },
  "basicScheme": {
    "type": "http",
    "scheme": "basic"
  },
  "apiKeyScheme": {
    "type": "apiKey",
    "in": "query",
    "name": "apiKey"
  },
  "cookieApiKeyScheme": {
    "type": "apiKey",
    "in": "cookie",
    "name": "apiKey"
  }
}

You can pass in a user object like this:

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "oauth2Scheme": "oauth-key",
  "basicScheme": {
    "user": "user",
    "pass": "pass",
  },
  "apiKeyScheme": "api-key",
  "cookieApiKeyScheme": "cookie-api-key"
}

And all of your security inputs will be prefilled.

One User with Multiple Projects

In some cases one user will have multiple sets of data. For example, a user can be apart of several teams all with a unique API Key. To support this functionality, just pass an array into a keys object with all of the values specific to that project.

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "isAdmin": true, // Optional
  "keys": [
    {
      "apiKey": "12345",
      "user": "Marc",
      "pass": "password",
      "key": "key1",
      "name": "Marc's 1st Project" // Required, used to select a project
    }, 
    {
      "apiKey": "678910",
      "user": "Marc2",
      "pass": "password2",
      "key": "key2",
      "name": "Marc's 2nd Project"
    }
  ]
}

When a variable that has multiple values is used in the documentation, for example <<key>>, the variable will have a dropdown allowing the user to pick which of the projects they want to be active. This dropdown affects all of the variables on your site, so switching the current project on one variable will make sure all of the other ones remain consistent.

Using Variables in the GraphQL Explorer

By setting specific variables in your user object, the GraphQL Explorer section will automatically use those values when the user is logged in. See GraphQL API Reference for more information about how you can get access to the beta.

OAuth Authentication

If graphql is set in the passed in JSON object (like in the following example), we will prefill in a Bearer Authentication header.

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "graphql": "dGhpcyBpcyBteSBiZWFyZXIgdG9rZW4="
}

{
  "name": "Marc Cuva",
  "email": "[email protected]",
  "graphql": "dGhpcyBpcyBteSBiZWFyZXIgdG9rZW4="
}