Skip to content

Commit

Permalink
Merge pull request #76 from knuckleswtf/overrides
Browse files Browse the repository at this point in the history 
Added support for overriding parts of the generated Postman collection or OpenAPI spec
@shalvah
shalvah authored Aug 23, 2020
2 parents 7adc169 + 8d82fe3 commit 06a5ee6
Showing 9 changed files with 545 additions and 54 deletions.
25 changes: 21 additions & 4 deletions config/scribe.php
View file
Original file line number Diff line number Diff line change
@@ -116,12 +116,9 @@
* Generate a Postman collection in addition to HTML docs.
* For 'static' docs, the collection will be generated to public/docs/collection.json.
* For 'laravel' docs, it will be generated to storage/app/scribe/collection.json.
* Setting `laravel.autoload` to true (above) will add routes for both the HTML and the Postman collection.
* Setting `laravel.add_routes` to true (above) will also add a route for the collection.
*/
'postman' => [
/*
* Specify whether the Postman collection should be generated.
*/
'enabled' => true,

/*
@@ -140,10 +137,30 @@
* https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html
*/
'auth' => null,

/*
* Manually override some generated content in the spec. Dot notation is supported.
*/
'overrides' => [
// 'info.version' => '2.0.0',
],
],

/*
* Generate an OpenAPI spec file in addition to docs webpage.
* For 'static' docs, the collection will be generated to public/docs/openapi.yaml.
* For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml.
* Setting `laravel.add_routes` to true (above) will also add a route for the spec.
*/
'openapi' => [
'enabled' => true,

/*
* Manually override some generated content in the spec. Dot notation is supported.
*/
'overrides' => [
// 'info.version' => '2.0.0',
],
],

/*
4 changes: 4 additions & 0 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
@@ -61,6 +61,8 @@ For `static` output, the collection will be created in `public/docs/collection.j

- `enabled`: Whether or not to generate a Postman API collection. Default: `true`

- `overrides`: List of fields to apply to the generated collection. Dot notation is supported. For instance, if you'd like to override the version (in the `info` object, you can set `overrides` to `['info.version' => '2.0.0']`.

- `description`: The description for the generated Postman collection.

- `base_url`: The base URL to be used in the Postman collection. If this is null, Scribe will use the value of [`base_url`](#base_url) set above.
@@ -74,6 +76,8 @@ For `static` output, the spec will be created in `public/docs/openapi.yaml`. For

- `enabled`: Whether or not to generate an OpenAPI spec. Default: `false`

- `overrides`: List of fields to apply to the generated spec. Dot notation is supported. For instance, if you'd like to override the version (in the `info` object, you can set `overrides` to `['info.version' => '2.0.0']`.

## Extraction settings
### `router`
The router to use when processing your routes. Can be `laravel` or `dingo`. Defaults to `laravel`.
4 changes: 4 additions & 0 deletions docs/generating-documentation.md
View file
Original file line number Diff line number Diff line change
@@ -23,6 +23,8 @@ You can configure Postman collection generation in the `postman` section of your

- To turn it off, set the `postman.enabled` config option to false.

- To override some fields in the generated collection, set the `openapi.overrides` config option to your changes. You can use dot notation to update specific nested fields. For instance, `['info.version' => '2.0.0']` will override the 'version` key in the 'info` object whenever generating.

- The base URL used in the Postman collection is the value of `config('app.url')` by default. To change this, set the value of the `postman.base_url` key.

- The name of the Postman collection will be derived from `config('app.name')` by default. To change this, set the value of the `title` key (not in the `postman` array). This will also set the title for your docs HTML page.
@@ -34,6 +36,8 @@ Scribe can also generate an OpenAPI spec file. This is disabled by default. You

- To enable it, set the `openapi.enabled` config option to `true`.

- To override some fields in the generated spec, set the `openapi.overrides` config option to your changes. You can use dot notation to update specific nested fields. For instance, `['info.version' => '2.0.0']` will override the 'version` key in the 'info` object whenever generating.

You can view the generated spec by visiting `public/docs/openapi.yaml` for `static` type, and `<your-app>/docs.openapi` for `laravel` type. This link will also be added to the sidebar of your docs.

## Customising the environment with `--env`
4 changes: 2 additions & 2 deletions src/Writing/PostmanCollectionWriter.php
View file
Original file line number Diff line number Diff line change
@@ -43,7 +43,7 @@ public function __construct(Collection $routeGroups, $baseUrl)
$this->auth = config('scribe.postman.auth');
}

public function makePostmanCollection()
public function generatePostmanCollection()
{
$collection = [
'variables' => [],
@@ -66,7 +66,7 @@ public function makePostmanCollection()
$collection['auth'] = $this->auth;
}

return json_encode($collection, JSON_PRETTY_PRINT);
return $collection;
}

protected function generateEndpointItem($route): array
18 changes: 16 additions & 2 deletions src/Writing/Writer.php
View file
Original file line number Diff line number Diff line change
@@ -218,7 +218,14 @@ public function generatePostmanCollection(Collection $routes)
['routeGroups' => $routes, 'baseUrl' => $this->postmanBaseUrl]
);

return $writer->makePostmanCollection();
$collection = $writer->generatePostmanCollection();
$overrides = $this->config->get('postman.overrides');
if (count($overrides)) {
foreach ($overrides as $key => $value) {
data_set($collection, $key, $value);
}
}
return json_encode($collection, JSON_PRETTY_PRINT);
}

public function generateOpenAPISpec(Collection $groupedEndpoints)
@@ -229,7 +236,14 @@ public function generateOpenAPISpec(Collection $groupedEndpoints)
['config' => $this->config]
);

return Yaml::dump($writer->generateSpecContent($groupedEndpoints), 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
$spec = $writer->generateSpecContent($groupedEndpoints);
$overrides = $this->config->get('openapi.overrides');
if (count($overrides)) {
foreach ($overrides as $key => $value) {
data_set($spec, $key, $value);
}
}
return Yaml::dump($spec, 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
}

protected function performFinalTasksForLaravelType(): void
185 changes: 185 additions & 0 deletions tests/Fixtures/collection-overridden.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
{
"variables": [],
"info": {
"name": "Custom API",
"_postman_id": "",
"description": "",
"schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json",
"version": "3.9.9"
},
"item": [
{
"name": "Group A",
"description": "",
"item": [
{
"name": "Example title.",
"request": {
"url": {
"protocol": "http",
"host": "localhost",
"path": "api\/withDescription",
"query": [],
"raw": "http:\/\/localhost\/api\/withDescription"
},
"method": "GET",
"header": [
{
"key": "Content-Type",
"value": "application\/json"
},
{
"key": "Accept",
"value": "application\/json"
}
],
"body": {
"mode": "raw",
"raw": "[]",
"options": {
"raw": {
"language": "json"
}
}
},
"description": "This will be the long description.\nIt can also be multiple lines long.",
"response": []
}
},
{
"name": "api\/withResponseTag",
"request": {
"url": {
"protocol": "http",
"host": "localhost",
"path": "api\/withResponseTag",
"query": [],
"raw": "http:\/\/localhost\/api\/withResponseTag"
},
"method": "GET",
"header": [
{
"key": "Content-Type",
"value": "application\/json"
},
{
"key": "Accept",
"value": "application\/json"
}
],
"body": {
"mode": "raw",
"raw": "[]",
"options": {
"raw": {
"language": "json"
}
}
},
"description": "",
"response": []
}
},
{
"name": "Endpoint with body parameters.",
"request": {
"url": {
"protocol": "http",
"host": "localhost",
"path": "api\/withBodyParameters",
"query": [],
"raw": "http:\/\/localhost\/api\/withBodyParameters"
},
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application\/json"
},
{
"key": "Accept",
"value": "application\/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"user_id\": 9,\n \"room_id\": \"consequatur\",\n \"forever\": false,\n \"another_one\": 11613.31890586,\n \"yet_another_param\": {\n \"name\": \"consequatur\"\n },\n \"even_more_param\": [\n 11613.31890586\n ],\n \"book\": {\n \"name\": \"consequatur\",\n \"author_id\": 17,\n \"pages_count\": 17\n },\n \"ids\": [\n 17\n ],\n \"users\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\"\n }\n ]\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"description": "",
"response": []
}
},
{
"name": "api\/withQueryParameters",
"request": {
"url": {
"protocol": "http",
"host": "localhost",
"path": "api\/withQueryParameters",
"query": [
{
"key": "location_id",
"value": "consequatur",
"description": "The id of the location.",
"disabled": false
},
{
"key": "user_id",
"value": "me",
"description": "The id of the user.",
"disabled": false
},
{
"key": "page",
"value": "4",
"description": "The page number.",
"disabled": false
},
{
"key": "filters",
"value": "consequatur",
"description": "The filters.",
"disabled": false
},
{
"key": "url_encoded",
"value": "%2B+%5B%5D%26%3D",
"description": "Used for testing that URL parameters will be URL-encoded where needed.",
"disabled": false
}
],
"raw": "http:\/\/localhost\/api\/withQueryParameters?location_id=consequatur&user_id=me&page=4&filters=consequatur&url_encoded=%2B+%5B%5D%26%3D"
},
"method": "GET",
"header": [
{
"key": "Content-Type",
"value": "application\/json"
},
{
"key": "Accept",
"value": "application\/json"
}
],
"body": {
"mode": "raw",
"raw": "[]",
"options": {
"raw": {
"language": "json"
}
}
},
"description": "",
"response": []
}
}
]
}
]
}
Loading

0 comments on commit 06a5ee6

Please sign in to comment.