From f7c629b7ef115d6d70e41cd5ce93deb024a97bc7 Mon Sep 17 00:00:00 2001 From: Josh Capener Date: Thu, 14 Sep 2023 07:48:00 +0100 Subject: [PATCH] * Scribe now natively supports all info fields described here https://swagger.io/specification/v3/#info-object --- config/scribe.php | 32 ++++++++++++++++++++++ src/Writing/OpenAPISpecWriter.php | 6 +++- tests/Fixtures/openapi.yaml | 8 ++++++ tests/GenerateDocumentation/OutputTest.php | 11 ++++++++ tests/Unit/OpenAPISpecWriterTest.php | 17 +++++++++++- 5 files changed, 72 insertions(+), 2 deletions(-) diff --git a/config/scribe.php b/config/scribe.php index a1662723..17f30b8a 100644 --- a/config/scribe.php +++ b/config/scribe.php @@ -16,6 +16,38 @@ */ 'description' => '', + /* + * A URL to the Terms of Service for the API. This MUST be in the form of a URL. + * See https://swagger.io/specification/v3/#info-object for more info + */ + 'terms_of_service' => null, + + /* + * Contact details for users of the Api to use to get more information or help. + * See https://swagger.io/specification/v3/#info-object for more info + */ + 'contact' => [ + 'name' => null, + 'email' => null, + 'url' => null, + ], + + /* + * License information about who can use the api and to what extent + * See https://swagger.io/specification/v3/#info-object for more info + */ + 'license' => [ + 'name' => null, + 'url' => null, + ], + + /* + * The current version string of the api + * See https://swagger.io/specification/v3/#info-object for more info + */ + 'version' => null, + + /* * The base URL displayed in the docs. If this is empty, Scribe will use the value of config('app.url') at generation time. * If you're using `laravel`` type, you can set this to a dynamic string, like '{{ config("app.tenant_url") }}' to get a dynamic base URL. diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php index 0857bfe6..b72bc6ae 100644 --- a/src/Writing/OpenAPISpecWriter.php +++ b/src/Writing/OpenAPISpecWriter.php @@ -41,7 +41,11 @@ public function generateSpecContent(array $groupedEndpoints): array 'info' => [ 'title' => $this->config->get('title') ?: config('app.name', ''), 'description' => $this->config->get('description', ''), - 'version' => '1.0.0', + 'version' => $this->config->get('version', ''), + 'summary' => $this->config->get('summary', ''), + 'termsOfService' => $this->config->get('terms_of_service', ''), + 'contact' => $this->config->get('contact', []), + 'license' => $this->config->get('license', []), ], 'servers' => [ [ diff --git a/tests/Fixtures/openapi.yaml b/tests/Fixtures/openapi.yaml index 9ea3a135..f6fa97cc 100644 --- a/tests/Fixtures/openapi.yaml +++ b/tests/Fixtures/openapi.yaml @@ -3,6 +3,14 @@ info: title: Laravel description: '' version: 3.9.9 + termsOfService: http://api.api.dev/terms-of-service + contact: + name: Scribe Support + email: support@scribe.test + url: https://scribe.knuckles.wtf/laravel + license: + name: MIT License + url: https://github.com/knuckleswtf/scribe/blob/master/LICENSE.md servers: - url: 'http://localhost' diff --git a/tests/GenerateDocumentation/OutputTest.php b/tests/GenerateDocumentation/OutputTest.php index 28e41a34..cf7d96c0 100644 --- a/tests/GenerateDocumentation/OutputTest.php +++ b/tests/GenerateDocumentation/OutputTest.php @@ -219,6 +219,17 @@ public function generated_openapi_spec_file_is_correct() RouteFacade::get('/api/echoesUrlParameters/{param}/{param2}/{param3?}/{param4?}', [TestController::class, 'echoesUrlParameters']); config(['scribe.openapi.enabled' => true]); + config(['scribe.version' => '2.4.1']); + config(['scribe.terms_of_service' => 'http://api.api.dev/terms-of-service']); + config(['scribe.contact' => [ + 'name' => 'Scribe Support', + 'email' => 'support@scribe.test', + 'url' => 'https://scribe.knuckles.wtf/laravel', + ]]); + config(['scribe.license' => [ + 'name' => 'MIT License', + 'url' => 'https://github.com/knuckleswtf/scribe/blob/master/LICENSE.md', + ]]); config(['scribe.openapi.overrides' => [ 'info.version' => '3.9.9', ]]); diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php index 52fa6cf2..d581eb04 100644 --- a/tests/Unit/OpenAPISpecWriterTest.php +++ b/tests/Unit/OpenAPISpecWriterTest.php @@ -22,6 +22,17 @@ class OpenAPISpecWriterTest extends TestCase 'title' => 'My Testy Testes API', 'description' => 'All about testy testes.', 'base_url' => 'http://api.api.dev', + 'version' => '2.4.1', + 'terms_of_service' => 'http://api.api.dev/terms-of-service', + 'contact' => [ + 'name' => 'Scribe Support', + 'email' => 'support@scribe.test', + 'url' => 'https://scribe.knuckles.wtf/laravel', + ], + 'license' => [ + 'name' => 'MIT License', + 'url' => 'https://github.com/knuckleswtf/scribe/blob/master/LICENSE.md', + ], ]; /** @test */ @@ -36,7 +47,11 @@ public function follows_correct_spec_structure() $this->assertEquals(OpenAPISpecWriter::SPEC_VERSION, $results['openapi']); $this->assertEquals($this->config['title'], $results['info']['title']); $this->assertEquals($this->config['description'], $results['info']['description']); - $this->assertNotEmpty($results['info']['version']); + $this->assertEquals($this->config['contact'], $results['info']['contact']); + $this->assertEquals($this->config['version'], $results['info']['version']); + $this->assertEquals($this->config['license'], $results['info']['license']); + $this->assertEquals($this->config['summary'], $results['info']['summary']); + $this->assertEquals($this->config['terms_of_service'], $results['info']['termsOfService']); $this->assertEquals($this->config['base_url'], $results['servers'][0]['url']); $this->assertIsArray($results['paths']); $this->assertGreaterThan(0, count($results['paths']));