Merge pull request #4 from AndreasElia/feature/config-examples

config and examples

README.md

@@ -5,7 +5,7 @@
 
 # Laravel API to Postman
 
-This package allows you to automatically generate a Postman collection based on your API routes.
+This package allows you to automatically generate a Postman collection based on your API routes. It also provides basic configuration and support for bearer auth tokens for routes behind an auth middleware.
 
 ## Postman Schema
 
@@ -19,19 +19,47 @@ Install the package:
 composer require andreaselia/laravel-api-to-postman
 ```
 
-With auto-discovery you don't need to do anything else.
+Publish the config file:
+
+```bash
+php artisan vendor:publish --provider="AndreasElia\PostmanGenerator\PostmanGeneratorServiceProvider" --tag="config"
+```
+
+## Configuration
+
+You can modify the `api-postman.php` config values:
+
+- `structured` - If you want folders to be generated based on route names.
+- `base_url` - The base URL for all of your endpoints.
+- `auth_middleware` - The middleware which wraps your authenticated API routes.
 
 ## Usage
 
+The output of the command being ran is your storage/app directory.
+
 To use the command simply run:
 
 ```bash
 php artisan export:postman
 ```
 
-- `--structured` generates routes in folders based on their namespace
-- `--bearer=<token>` generates a token variable in Postman for the specified token
-- `--base-url=<base_url>` defaults to https://api.example.com/ unless specified
+The following usage will generate routes with the bearer token specified.
+
+```bash
+php artisan export:postman --bearer=1|XXNKXXqJjfzG8XXSvXX1Q4pxxnkXmp8tT8TXXKXX
+```
+
+## Examples
+
+This is with the default configuration and a bearer token passed in:
+
+```bash
+php artisan export:postman --bearer=123456789
+```
+
+- [Example routes](/examples/api.php)
+- [Example default output](/examples/2021_02_04_151948_postman.json)
+- [Example structured output](/examples/2021_02_04_155327_postman.json)
 
 ## Contributing
 

config/api-postman.php

@@ -0,0 +1,31 @@
+<?php
+
+return [
+
+ /*
+ * Structured.
+ *
+ * If you want folders to be generated based on namespace.
+ */
+
+ 'structured' => false,
+
+ /*
+ * Base URL.
+ *
+ * The base URL for all of your endpoints.
+ */
+
+ 'base_url' => env('APP_URL', 'http://localhost'),
+
+ /*
+ * Auth Middleware.
+ *
+ * The middleware which wraps your authenticated API routes.
+ *
+ * E.g. auth:api, auth:sanctum
+ */
+
+ 'auth_middleware' => 'auth:api',
+
+];

examples/2021_02_04_151948_postman.json

@@ -0,0 +1,121 @@
+{
+ "variable": [{
+ "key": "base_url",
+ "value": "https:\/\/api.example.com\/"
+ }, {
+ "key": "token",
+ "value": "123456789"
+ }],
+ "info": {
+ "name": "2021_02_04_151948_postman",
+ "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json"
+ },
+ "item": [{
+ "name": "api",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api",
+ "host": "{{base_url}}\/api"
+ }
+ }
+ }, {
+ "name": "api\/posts",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts",
+ "host": "{{base_url}}\/api\/posts"
+ }
+ }
+ }, {
+ "name": "api\/posts",
+ "request": {
+ "method": "POST",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts",
+ "host": "{{base_url}}\/api\/posts"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "PUT",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "PATCH",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "DELETE",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/user",
+ "request": {
+ "method": "POST",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }, {
+ "key": "Authorization",
+ "value": "Bearer {{token}}"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/user",
+ "host": "{{base_url}}\/api\/user"
+ }
+ }
+ }]
+}

examples/2021_02_04_155327_postman.json

@@ -0,0 +1,130 @@
+{
+ "variable": [{
+ "key": "base_url",
+ "value": "https:\/\/api.example.com\/"
+ }, {
+ "key": "token",
+ "value": "123456789"
+ }],
+ "info": {
+ "name": "2021_02_04_155327_postman",
+ "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json"
+ },
+ "item": [{
+ "name": "home",
+ "item": [{
+ "name": "api",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api",
+ "host": "{{base_url}}\/api"
+ }
+ }
+ }]
+ }, {
+ "name": "posts",
+ "item": [{
+ "name": "api\/posts",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts",
+ "host": "{{base_url}}\/api\/posts"
+ }
+ }
+ }, {
+ "name": "api\/posts",
+ "request": {
+ "method": "POST",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts",
+ "host": "{{base_url}}\/api\/posts"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "GET",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "PUT",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "PATCH",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }, {
+ "name": "api\/posts\/{post}",
+ "request": {
+ "method": "DELETE",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/posts\/{post}",
+ "host": "{{base_url}}\/api\/posts\/{post}"
+ }
+ }
+ }]
+ }, {
+ "name": "user",
+ "item": [{
+ "name": "api\/user",
+ "request": {
+ "method": "POST",
+ "header": [{
+ "key": "Content-Type",
+ "value": "application\/json"
+ }, {
+ "key": "Authorization",
+ "value": "Bearer {{token}}"
+ }],
+ "url": {
+ "raw": "{{base_url}}\/api\/user",
+ "host": "{{base_url}}\/api\/user"
+ }
+ }
+ }]
+ }]
+}

examples/api.php

@@ -0,0 +1,13 @@
+<?php
+
+use App\Http\Controllers\HomeController;
+use App\Http\Controllers\UserController;
+use Illuminate\Support\Facades\Route;
+
+Route::get('/', HomeController::class)->name('home');
+
+Route::apiResource('posts', 'PostController');
+
+Route::middleware('auth:api')->group(function () {
+ Route::post('/user', UserController::class)->name('user');
+});