The conjure-postman from palantir

conjure-postman's Introduction

conjure-postman

Generate Postman Collections for interacting with Conjure defined APIs.

Usage

conjure-postman is an executable which conforms to RFC 002.

usage: conjure-postman generate <target> <output> [--apiPath <apiPath>]
       [--productDescription <description>] --productName <name>
       --productVersion <version>
    --apiPath <apiPath>
    --productDescription <description>
    --productName <name>                 product name
    --productVersion <version>           version number of target product

Generated collections

conjure-postman generates collections in the Postman Collections 2.1.0 format.

Collections contain one folder per service, which contain one request per Endpoint Definition.

Variables

Requests require the following variables to be set:

Variable	Description	Example
`{{HOSTNAME}}`	Hostname (including protocol)	`https://site.com`
`{{PORT}}`	Port to use for request	`443`
`{{AUTH_TOKEN}}`	Bearer token (only token part)	`eyJhb...`
`{{%s_API_BASE}}`	Path to API base of product	`/service/api`

Collection Defaults

{{PORT}} defaults to 443
{{%s_API_BASE}}
- %s will be the name of the service, uppercased and underscored.
- When --apiPath is provided it will be used as the value of the variable.

Overrides and non-default options should be set in an Environment.

Body Templates

When a request has a conjure bean as a body argument a template will be provided based on the Bean definition.

Primitives

Primitives are templated in quoted double-curly braces (e.g. "{{STRING}}", "{{INTEGER}}" or "{{BINARY}}"). When filling in the template non-string types should not include quotes.

Alias Types

Alias type templates are the name of the alias followed by the referenced type in parenthesis. (e.g. "{{ Name(STRING) }}")

Lists/Sets/Maps

Collection type templates are an example of a single element.

Enumerations

Enumeration templates are a pipe separated list of all possible values for the enum.

Union Types

Union types are will provide a pipe separated list of possible types and an example template for each type in a map named oneOf. One type should be chosen and the oneOf block should be replaced with the corresponding template.

Recursive Types

Recursive references in templates will be the type name in quoted double curly braces.

Tests

Postman Tests will be configured to expect a successful request and a valid JSON body where appropriate.

conjure-postman's People

Contributors

Stargazers

Watchers

conjure-postman's Issues

param-type of query does not include docs

When building for Postman, docs for query parameters are not included, though docs for path variables are.

I have this in my input:

"args" : [ {
        "argName" : "walletAddress",
        "type" : {
          "type" : "primitive",
          "primitive" : "STRING"
        },
        "paramType" : {
          "type" : "path",
          "path" : { }
        },
        "docs" : "The requested wallet address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically.",
        "markers" : [ ],
        "tags" : [ ]
      }, {
        "argName" : "testnets",
        "type" : {
          "type" : "primitive",
          "primitive" : "BOOLEAN"
        },
        "paramType" : {
          "type" : "query",
          "query" : {
            "paramId" : "testnets"
          }
        },
        "docs" : "Set to true to include testnets with activity in the response. By default, it's set to `false` and only returns mainnet activity.",
        "markers" : [ ],
        "tags" : [ ]
      } ]

Note the "docs" field is populated for both parameter types above. However, the description field for query is not created, like it is for variable:

"variable":[{
    "key": "walletAddress",
    "description": "The requested wallet address. Passing in an `ENS`, `RNS`, `Lens Handle`, or an `Unstoppable Domain` resolves automatically."
  }],
"query":[{
  "key": "testnets",
  "value": "",
  "disabled": false
}]

Recommend Projects

palantir / conjure-postman Goto Github PK