This library helps you generate a Postman collection from your Phoenix router (MyApp.Router).
You can document your endpoints using @doc annotations for params, body, form data, and more.
Pipelines (plugs) can also be auto-scanned and added to the collection automatically.

Example generated collection:

This library uses the official Postman schema: https://schema.postman.com/

Table of Contents

• Installation
• Description and Titles
• Query Parameters
• Body Parameters
• Form Data
• Authentication Tokens
• Organizing Folders
• Mix Commands
• Todo
• Feedback
• Changelog

Installation

If available in Hex, the package can be installed
by adding fast_postman_collection to your list of dependencies in mix.exs:

def deps do
  [
    {:fast_postman_collection, "~> 0.1.8"}
  ]
end

Configure fast_postman_collection

• router → your Phoenix router module (required)
• pipe_tokens → put in your auth bearer (pipe_tokens: a list of pipeline plugs (like :admin_auth) that should automatically add a Bearer token in the Postman request headers.)
• variables → variables to include in the Postman collection (optional)
• file_path_collection → path to save the generated collection (optional)

config(:fast_postman_collection,
  pipe_tokens: [:admin_auth, :user_auth],
  name_collection: "My collection",
  router: MyApp.Router,
  variables: [
    %{
      key: "host",
      value: "http://localhost:4000"
    }
  ]
)

When you add router to your configuration, it will be able to generate a collection using the command - mix fs.get_collection

Description and Title of collection

@moduledoc """
# Post Controller
This will be used as the folder name in the generated Postman collection.
"""

@doc """
# Create Post
This will be used as the request title in the Postman collection.

Use this endpoint to create a new post.
All content inside this doc block will be added to the request description in the collection.
"""

If you don’t provide a @doc annotation, the default name will be taken from the module or function name.

Params in Your Collection

These parameters will be included in the URL as query strings.
For example, the generated URL might look like: ?limit=0&page=1

@doc params: %{
  limit: 0,
  page: %{
    key: "page",
    value: 1,
    description: "Page number for pagination"
  }
}
def index(conn, params) do
  json(conn, params)
end

Body Parameters

These parameters will be included in the request body.
By default, the body is sent in JSON format.

This is how you define a request body in JSON format:

@doc """
# Create post
"""
@doc body: %{
        post: %{
          title: ""
        }
      }
def create_post(conn, params) do
  json(conn, params)
end

Formdata options

To send form data (e.g. file uploads):

@doc mode: "formdata"
@doc formdata: [
        %{
          key: "image",
          value: nil,
          type: "file"
        }
      ]

How to Auto-Scan and Apply Authentication Tokens

How to auto scan and autoput your pipe’s token

Example

router.ex

scope "/user" do
  pipe_through(:admin_auth)
  get("/", UserController, :index)
end

config.exs

config(:fast_postman_collection,
  pipe_tokens: [:admin_auth, :user_auth]

All tokens puts and scans from your pipelines

Extract Token from Response Automatically

You can also automatically insert tokens into variables from a response:

 @doc auth_pre_request: %{is_enabled: true, from_resp_token: "token", variable_token: "admin_variable"}

Organizing Folders in the Collection

You can use @moduledoc folder_path: “Admin” to place your module’s requests inside a specific folder in the Postman collection.

The final folder structure will look like:
Admin / UserController

Example

defmodule MyAppWeb.AdminUserController do
  use MyAppWeb, :controller
  @moduledoc folder_path: "Admin"
  # this module puts to /admin/user controller
  @moduledoc """
  # user controller
  """

end

Mix commands

• mix fs.get_collection: This command generate in your directory file with collection

Todo

• filtering in mix fs.get_collection

You like the idea?

If you like the idea of the library, write in this “issue” on github and I will add this functionality as soon as I have free time.

Documentation:

• Hex Docs Fast Postman Collection