config = $config ?: new DocumentationConfig(config('scribe', [])); $this->baseUrl = ($this->config->get('postman.base_url') ?: $this->config->get('base_url')) ?: config('app.url'); } public function generatePostmanCollection(Collection $groupedEndpoints) { $collection = [ 'variable' => [ [ 'id' => 'baseUrl', 'key' => 'baseUrl', 'type' => 'string', 'name' => 'string', 'value' => parse_url($this->baseUrl, PHP_URL_HOST) ?: $this->baseUrl, // if there's no protocol, parse_url might fail ], ], 'info' => [ 'name' => $this->config->get('title') ?: config('app.name'), '_postman_id' => Uuid::uuid4()->toString(), 'description' => $this->config->get('description', ''), 'schema' => "https://schema.getpostman.com/json/collection/v" . self::VERSION . "/collection.json", ], 'item' => $groupedEndpoints->map(function (Collection $routes, $groupName) { return [ 'name' => $groupName, 'description' => $routes->first()['metadata']['groupDescription'], 'item' => $routes->map(\Closure::fromCallable([$this, 'generateEndpointItem']))->toArray(), ]; })->values()->toArray(), 'auth' => $this->generateAuthObject(), ]; return $collection; } protected function generateAuthObject() { if (!$this->config->get('auth.enabled')) { return [ 'type' => 'noauth', ]; } switch ($this->config->get('auth.in')) { case "basic": return [ 'type' => 'basic', ]; case "bearer": return [ 'type' => 'bearer', ]; default: return [ 'type' => 'apikey', 'apikey' => [ [ 'key' => 'in', 'value' => $this->config->get('auth.in'), 'type' => 'string', ], [ 'key' => 'key', 'value' => $this->config->get('auth.name'), 'type' => 'string', ], ], ]; } } protected function generateEndpointItem($endpoint): array { $endpointItem = [ 'name' => $endpoint['metadata']['title'] !== '' ? $endpoint['metadata']['title'] : $endpoint['uri'], 'request' => [ 'url' => $this->generateUrlObject($endpoint), 'method' => $endpoint['methods'][0], 'header' => $this->resolveHeadersForEndpoint($endpoint), 'body' => empty($endpoint['bodyParameters']) ? null : $this->getBodyData($endpoint), 'description' => $endpoint['metadata']['description'] ?? null, ], 'response' => [], ]; if (($endpoint['metadata']['authenticated'] ?? false) === false) { $endpointItem['request']['auth'] = ['type' => 'noauth']; } return $endpointItem; } protected function getBodyData(array $endpoint): array { $body = []; $contentType = $endpoint['headers']['Content-Type'] ?? null; switch ($contentType) { case 'multipart/form-data': $inputMode = 'formdata'; break; case 'application/json': default: $inputMode = 'raw'; } $body['mode'] = $inputMode; $body[$inputMode] = []; switch ($inputMode) { case 'formdata': foreach ($endpoint['cleanBodyParameters'] as $key => $value) { $params = [ 'key' => $key, 'value' => $value, 'type' => 'text', ]; $body[$inputMode][] = $params; } foreach ($endpoint['fileParameters'] as $key => $value) { while (is_array($value)) { // For arrays of files, just send the first one $key .= '[]'; $value = $value[0]; } $params = [ 'key' => $key, 'src' => [], 'type' => 'file', ]; $body[$inputMode][] = $params; } break; case 'raw': default: $body[$inputMode] = json_encode($endpoint['cleanBodyParameters'], JSON_PRETTY_PRINT); } return $body; } protected function resolveHeadersForEndpoint($route) { [$where, $authParam] = $this->getAuthParamToExclude(); $headers = collect($route['headers']); if ($where === 'header') { unset($headers[$authParam]); } $headers = $headers ->union([ 'Accept' => 'application/json', ]) ->map(function ($value, $header) { // Allow users to write ['header' => '@{{value}}'] in config // and have it rendered properly as {{value}} in the Postman collection. $value = str_replace('@{{', '{{', $value); return [ 'key' => $header, 'value' => $value, ]; }) ->values() ->all(); return $headers; } protected function generateUrlObject($route) { $base = [ 'protocol' => Str::startsWith($this->baseUrl, 'https') ? 'https' : 'http', 'host' => '{{baseUrl}}', // Change laravel/symfony URL params ({example}) to Postman style, prefixed with a colon 'path' => preg_replace_callback('/\{(\w+)\??}/', function ($matches) { return ':' . $matches[1]; }, $route['uri']), ]; $query = []; [$where, $authParam] = $this->getAuthParamToExclude(); foreach ($route['queryParameters'] ?? [] as $name => $parameterData) { if ($where === 'query' && $authParam === $name) { continue; } if (Str::endsWith($parameterData['type'], '[]') || $parameterData['type'] === 'object') { $values = empty($parameterData['value']) ? [] : $parameterData['value']; foreach ($values as $index => $value) { // PHP's parse_str supports array query parameters as filters[0]=name&filters[1]=age OR filters[]=name&filters[]=age // Going with the first to also support object query parameters // See https://www.php.net/manual/en/function.parse-str.php $query[] = [ 'key' => urlencode("{$name}[$index]"), 'value' => urlencode($value), 'description' => strip_tags($parameterData['description']), // Default query params to disabled if they aren't required and have empty values 'disabled' => !($parameterData['required'] ?? false) && empty($parameterData['value']), ]; } } else { $query[] = [ 'key' => urlencode($name), 'value' => urlencode($parameterData['value']), 'description' => strip_tags($parameterData['description']), // Default query params to disabled if they aren't required and have empty values 'disabled' => !($parameterData['required'] ?? false) && empty($parameterData['value']), ]; } } $base['query'] = $query; // Create raw url-parameter (Insomnia uses this on import) $queryString = collect($base['query'] ?? [])->map(function ($queryParamData) { return $queryParamData['key'] . '=' . $queryParamData['value']; })->implode('&'); $base['raw'] = sprintf('%s://%s/%s%s', $base['protocol'], $base['host'], $base['path'], $queryString ? "?{$queryString}" : null ); $urlParams = collect($route['urlParameters']); if ($urlParams->isEmpty()) { return $base; } $base['variable'] = $urlParams->map(function ($parameter, $name) { return [ 'id' => $name, 'key' => $name, 'value' => urlencode($parameter['value']), 'description' => $parameter['description'], ]; })->values()->toArray(); return $base; } private function getAuthParamToExclude(): array { if (!$this->config->get('auth.enabled')) { return [null, null]; } if (in_array($this->config->get('auth.in'), ['bearer', 'basic'])) { return ['header', 'Authorization']; } else { return [$this->config->get('auth.in'), $this->config->get('auth.name')]; } } }