Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/master'
Browse files Browse the repository at this point in the history
  • Loading branch information
shalvah committed Aug 23, 2020
2 parents bd98cbe + 06a5ee6 commit 8122820
Show file tree
Hide file tree
Showing 11 changed files with 557 additions and 67 deletions.
25 changes: 21 additions & 4 deletions config/scribe.php
Original file line number Diff line number Diff line change
Expand Up @@ -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,

/*
Expand All @@ -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',
],
],

/*
Expand Down
6 changes: 5 additions & 1 deletion docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,19 +61,23 @@ 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.

- `auth`: The "Auth" section that should appear in the postman collection. See the [Postman schema docs](https://schema.getpostman.com/json/collection/v2.0.0/docs/index.html) for more information.

### `openapi`
Scribe can also generate an OpenAPI (Swagger) spec for your routes. This section is where you can configure or disable that.
Scribe can also generate an OpenAPI (Swagger) spec for your routes (disabled by default). This section is where you can configure or enable that.

For `static` output, the spec will be created in `public/docs/openapi.yaml`. For `laravel` output, the spec will be generated to `storage/app/scribe/openapi.yaml`. Setting `laravel.add_routes` to `true` will add a `/docs.openapi` endpoint to fetch it.

- `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`.
Expand Down
4 changes: 4 additions & 0 deletions docs/generating-documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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`
Expand Down
21 changes: 10 additions & 11 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,16 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
```eval_rst
.. Tip:: Looking to document your Node.js APIs? Check out `Scribe for JS <https://github.com/knuckleswtf/scribe-js>`_.
```
## Features
- Pretty HTML documentation page, with included code samples and friendly text
- Markdown source files that can be edited to modify docs
- Extracts body parameters information from FormRequests
- Safely calls API endpoints to generate sample responses, with authentication and other custom configuration supported
- Supports generating responses from Transformers or Eloquent API Resources
- Supports Postman collection and OpenAPI (Swagger) spec generation
- Included UI components for additional styling
- Easily customisable with custom views
- Easily extensible with custom strategies

## Contents
```eval_rst
Expand All @@ -31,17 +41,6 @@ Generate API documentation for humans from your Laravel/Lumen/[Dingo](https://gi
contributing
```

## Features
- Pretty HTML documentation page, with included code samples and friendly text
- Markdown source files that can be edited to modify docs
- Extracts body parameters information from FormRequests
- Safely calls API endpoints to generate sample responses, with authentication and other custom configuration supported
- Supports generating responses from Transformers or Eloquent API Resources
- Supports Postman collection and OpenAPI (Swagger) spec generation
- Included UI components for additional styling
- Easily customisable with custom views
- Easily extensible with custom strategies

## Installation
PHP 7.2.5 and Laravel/Lumen 5.8 or higher are required.

Expand Down
2 changes: 1 addition & 1 deletion src/Extracting/Strategies/Responses/ResponseCalls.php
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ protected function prepareRequest(Route $route, array $rulesToApply, array $urlP
$method = array_shift($routeMethods);
$cookies = isset($rulesToApply['cookies']) ? $rulesToApply['cookies'] : [];

// Note that we initialise the request with the bodyPatams here
// Note that we initialise the request with the bodyParams here
// and later still add them to the ParameterBag (`addBodyParameters`)
// The first is so the body params get added to the request content
// (where Laravel reads body from)
Expand Down
4 changes: 2 additions & 2 deletions src/Writing/PostmanCollectionWriter.php
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ public function __construct(Collection $routeGroups, $baseUrl)
$this->auth = config('scribe.postman.auth');
}

public function makePostmanCollection()
public function generatePostmanCollection()
{
$collection = [
'variables' => [],
Expand All @@ -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
Expand Down
18 changes: 16 additions & 2 deletions src/Writing/Writer.php
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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
Expand Down
185 changes: 185 additions & 0 deletions tests/Fixtures/collection-overridden.json
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 8122820

Please sign in to comment.