Skip to content

Commit 06a5ee6

Browse files
shalvahshalvah
authored
Merge pull request #76 from knuckleswtf/overrides
Added support for overriding parts of the generated Postman collection or OpenAPI spec
2 parents 7adc169 + 8d82fe3 commit 06a5ee6

File tree

9 files changed

+545
-54
lines changed

9 files changed

+545
-54
lines changed

‎config/scribe.php‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -116,12 +116,9 @@
116116
* Generate a Postman collection in addition to HTML docs.
117117
* For 'static' docs, the collection will be generated to public/docs/collection.json.
118118
* For 'laravel' docs, it will be generated to storage/app/scribe/collection.json.
119-
* Setting `laravel.autoload` to true (above) will add routes for both the HTML and the Postman collection.
119+
* Setting `laravel.add_routes` to true (above) will also add a route for the collection.
120120
*/
121121
'postman' => [
122-
/*
123-
* Specify whether the Postman collection should be generated.
124-
*/
125122
'enabled' => true,
126123

127124
/*
@@ -140,10 +137,30 @@
140137
* https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html
141138
*/
142139
'auth' => null,
140+
141+
/*
142+
* Manually override some generated content in the spec. Dot notation is supported.
143+
*/
144+
'overrides' => [
145+
// 'info.version' => '2.0.0',
146+
],
143147
],
144148

149+
/*
150+
* Generate an OpenAPI spec file in addition to docs webpage.
151+
* For 'static' docs, the collection will be generated to public/docs/openapi.yaml.
152+
* For 'laravel' docs, it will be generated to storage/app/scribe/openapi.yaml.
153+
* Setting `laravel.add_routes` to true (above) will also add a route for the spec.
154+
*/
145155
'openapi' => [
146156
'enabled' => true,
157+
158+
/*
159+
* Manually override some generated content in the spec. Dot notation is supported.
160+
*/
161+
'overrides' => [
162+
// 'info.version' => '2.0.0',
163+
],
147164
],
148165

149166
/*

‎docs/config.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ For `static` output, the collection will be created in `public/docs/collection.j
6161

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

64+
- `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']`.
65+
6466
- `description`: The description for the generated Postman collection.
6567

6668
- `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
7476

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

79+
- `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']`.
80+
7781
## Extraction settings
7882
### `router`
7983
The router to use when processing your routes. Can be `laravel` or `dingo`. Defaults to `laravel`.

‎docs/generating-documentation.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ You can configure Postman collection generation in the `postman` section of your
2323

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

26+
- 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.
27+
2628
- 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.
2729

2830
- 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
3436

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

39+
- 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.
40+
3741
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.
3842

3943
## Customising the environment with `--env`

‎src/Writing/PostmanCollectionWriter.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ public function __construct(Collection $routeGroups, $baseUrl)
4343
$this->auth = config('scribe.postman.auth');
4444
}
4545

46-
public function makePostmanCollection()
46+
public function generatePostmanCollection()
4747
{
4848
$collection = [
4949
'variables' => [],
@@ -66,7 +66,7 @@ public function makePostmanCollection()
6666
$collection['auth'] = $this->auth;
6767
}
6868

69-
return json_encode($collection, JSON_PRETTY_PRINT);
69+
return $collection;
7070
}
7171

7272
protected function generateEndpointItem($route): array

‎src/Writing/Writer.php‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,14 @@ public function generatePostmanCollection(Collection $routes)
218218
['routeGroups' => $routes, 'baseUrl' => $this->postmanBaseUrl]
219219
);
220220

221-
return $writer->makePostmanCollection();
221+
$collection = $writer->generatePostmanCollection();
222+
$overrides = $this->config->get('postman.overrides');
223+
if (count($overrides)) {
224+
foreach ($overrides as $key => $value) {
225+
data_set($collection, $key, $value);
226+
}
227+
}
228+
return json_encode($collection, JSON_PRETTY_PRINT);
222229
}
223230

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

232-
return Yaml::dump($writer->generateSpecContent($groupedEndpoints), 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
239+
$spec = $writer->generateSpecContent($groupedEndpoints);
240+
$overrides = $this->config->get('openapi.overrides');
241+
if (count($overrides)) {
242+
foreach ($overrides as $key => $value) {
243+
data_set($spec, $key, $value);
244+
}
245+
}
246+
return Yaml::dump($spec, 10, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
233247
}
234248

235249
protected function performFinalTasksForLaravelType(): void

‎tests/Fixtures/collection-overridden.json‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
{
2+
"variables": [],
3+
"info": {
4+
"name": "Custom API",
5+
"_postman_id": "",
6+
"description": "",
7+
"schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.0.0\/collection.json",
8+
"version": "3.9.9"
9+
},
10+
"item": [
11+
{
12+
"name": "Group A",
13+
"description": "",
14+
"item": [
15+
{
16+
"name": "Example title.",
17+
"request": {
18+
"url": {
19+
"protocol": "http",
20+
"host": "localhost",
21+
"path": "api\/withDescription",
22+
"query": [],
23+
"raw": "http:\/\/localhost\/api\/withDescription"
24+
},
25+
"method": "GET",
26+
"header": [
27+
{
28+
"key": "Content-Type",
29+
"value": "application\/json"
30+
},
31+
{
32+
"key": "Accept",
33+
"value": "application\/json"
34+
}
35+
],
36+
"body": {
37+
"mode": "raw",
38+
"raw": "[]",
39+
"options": {
40+
"raw": {
41+
"language": "json"
42+
}
43+
}
44+
},
45+
"description": "This will be the long description.\nIt can also be multiple lines long.",
46+
"response": []
47+
}
48+
},
49+
{
50+
"name": "api\/withResponseTag",
51+
"request": {
52+
"url": {
53+
"protocol": "http",
54+
"host": "localhost",
55+
"path": "api\/withResponseTag",
56+
"query": [],
57+
"raw": "http:\/\/localhost\/api\/withResponseTag"
58+
},
59+
"method": "GET",
60+
"header": [
61+
{
62+
"key": "Content-Type",
63+
"value": "application\/json"
64+
},
65+
{
66+
"key": "Accept",
67+
"value": "application\/json"
68+
}
69+
],
70+
"body": {
71+
"mode": "raw",
72+
"raw": "[]",
73+
"options": {
74+
"raw": {
75+
"language": "json"
76+
}
77+
}
78+
},
79+
"description": "",
80+
"response": []
81+
}
82+
},
83+
{
84+
"name": "Endpoint with body parameters.",
85+
"request": {
86+
"url": {
87+
"protocol": "http",
88+
"host": "localhost",
89+
"path": "api\/withBodyParameters",
90+
"query": [],
91+
"raw": "http:\/\/localhost\/api\/withBodyParameters"
92+
},
93+
"method": "POST",
94+
"header": [
95+
{
96+
"key": "Content-Type",
97+
"value": "application\/json"
98+
},
99+
{
100+
"key": "Accept",
101+
"value": "application\/json"
102+
}
103+
],
104+
"body": {
105+
"mode": "raw",
106+
"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}",
107+
"options": {
108+
"raw": {
109+
"language": "json"
110+
}
111+
}
112+
},
113+
"description": "",
114+
"response": []
115+
}
116+
},
117+
{
118+
"name": "api\/withQueryParameters",
119+
"request": {
120+
"url": {
121+
"protocol": "http",
122+
"host": "localhost",
123+
"path": "api\/withQueryParameters",
124+
"query": [
125+
{
126+
"key": "location_id",
127+
"value": "consequatur",
128+
"description": "The id of the location.",
129+
"disabled": false
130+
},
131+
{
132+
"key": "user_id",
133+
"value": "me",
134+
"description": "The id of the user.",
135+
"disabled": false
136+
},
137+
{
138+
"key": "page",
139+
"value": "4",
140+
"description": "The page number.",
141+
"disabled": false
142+
},
143+
{
144+
"key": "filters",
145+
"value": "consequatur",
146+
"description": "The filters.",
147+
"disabled": false
148+
},
149+
{
150+
"key": "url_encoded",
151+
"value": "%2B+%5B%5D%26%3D",
152+
"description": "Used for testing that URL parameters will be URL-encoded where needed.",
153+
"disabled": false
154+
}
155+
],
156+
"raw": "http:\/\/localhost\/api\/withQueryParameters?location_id=consequatur&user_id=me&page=4&filters=consequatur&url_encoded=%2B+%5B%5D%26%3D"
157+
},
158+
"method": "GET",
159+
"header": [
160+
{
161+
"key": "Content-Type",
162+
"value": "application\/json"
163+
},
164+
{
165+
"key": "Accept",
166+
"value": "application\/json"
167+
}
168+
],
169+
"body": {
170+
"mode": "raw",
171+
"raw": "[]",
172+
"options": {
173+
"raw": {
174+
"language": "json"
175+
}
176+
}
177+
},
178+
"description": "",
179+
"response": []
180+
}
181+
}
182+
]
183+
}
184+
]
185+
}

0 commit comments

Comments
 (0)