Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Format OpenAPI response codes as strings #908

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Format OpenAPI response codes as strings #908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions config/scribe.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@
// A short description of your API. Will be included in the docs webpage, Postman collection and OpenAPI spec.
'description' => '',

'contact' => [
'name' => '',
'url' => '',
'email' => '',
],

// 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.
'base_url' => null,
Expand Down Expand Up @@ -127,8 +133,7 @@

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>
INTRO
,
INTRO,

// Example requests for each endpoint will be shown in each of these languages.
// Supported options are: bash, javascript, php, python
Expand Down
5 changes: 5 additions & 0 deletions config/scribe_new.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,11 @@
theme: 'default',
title: null,
description: '',
contact: [
"name" => '',
"url" => '',
"email" => '',
],
baseUrls: [
"production" => config("app.base_url"),
],
Expand Down
30 changes: 11 additions & 19 deletions src/Config/Output.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ public static function with(
string $theme = 'default',
string $title = null,
string $description = '',
array $contact = [],
array $baseUrls = [],
array $exampleLanguages = ['bash', 'javascript'],
bool $logo = false,
Expand All @@ -18,15 +19,15 @@ public static function with(
array $postman = ['enabled' => true],
array $openApi = ['enabled' => true],
array $tryItOut = ['enabled' => true],
): static
{
): static {
return new static(...get_defined_vars());
}

public function __construct(
public string $theme = 'default',
public ?string $title = null,
public string $description = '',
public array $contact = [],
public array $baseUrls = [], /* If empty, Scribe will use config('app.url') */
public array $groupsOrder = [],
public string $introText = "",
Expand All @@ -38,56 +39,48 @@ public function __construct(
public array $postman = ['enabled' => true],
public array $openApi = ['enabled' => true],
public array $tryItOut = ['enabled' => true],
)
{
}
) {}

public static function laravelType(
bool $addRoutes = true,
string $docsUrl = '/docs',
string $assetsDirectory = null,
array $middleware = [],
): array
{
): array {
return ['laravel', get_defined_vars()];
}

public static function staticType(
string $outputPath = 'public/docs',
): array
{
): array {
return ['static', get_defined_vars()];
}

public static function externalStaticType(
string $outputPath = 'public/docs',
): array
{
): array {
return ['external_static', get_defined_vars()];
}

public static function externalLaravelType(
bool $addRoutes = true,
string $docsUrl = '/docs',
array $middleware = [],
): array
{
): array {
return ['external_laravel', get_defined_vars()];
}

public static function postman(
bool $enabled = true,
array $overrides = [],
): array
{
): array {
return get_defined_vars();
}

public static function openApi(
bool $enabled = true,
array $overrides = [],
): array
{
): array {
return get_defined_vars();
}

Expand All @@ -96,8 +89,7 @@ public static function tryItOut(
string $baseUrl = null,
bool $useCsrf = false,
string $csrfUrl = '/sanctum/csrf-cookie',
): array
{
): array {
return get_defined_vars();
}
}
14 changes: 9 additions & 5 deletions src/Writing/OpenAPISpecWriter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,12 @@ 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' => config('app.version', ''),
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a standard Laravel config variable, is it?

'contact' => [
'name' => $this->config->get('contact.name', ''),
'url' => $this->config->get('contact.url', ''),
'email' => $this->config->get('contact.email', ''),
],
],
'servers' => [
[
Expand Down Expand Up @@ -249,7 +254,6 @@ protected function generateEndpointRequestBodySpec(OutputEndpointData $endpoint)
}

$body['content'][$contentType]['schema'] = $schema;

}

// return object rather than empty array, so can get properly serialised as object
Expand Down Expand Up @@ -400,7 +404,7 @@ protected function generateResponseContentSpec(?string $responseContent, OutputE
],
'example' => $decoded,
],
],
],
];

case 'object':
Expand Down Expand Up @@ -547,7 +551,7 @@ public function generateFieldData($field): array
'type' => 'object',
'description' => $field->description ?: '',
'example' => $field->example,
'nullable'=> $field->nullable,
'nullable' => $field->nullable,
'properties' => $this->objectIfEmpty(collect($field->__fields)->mapWithKeys(function ($subfield, $subfieldName) {
return [$subfieldName => $this->generateFieldData($subfield)];
})->all()),
Expand Down Expand Up @@ -656,7 +660,7 @@ public function filterRequiredFields(OutputEndpointData $endpoint, array $proper

return $required;
}

/*
* Set the description for the schema. If the field has a description, it is set in the schema.
*/
Expand Down
10 changes: 5 additions & 5 deletions src/Writing/Writer.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ public function generateOpenAPISpec(array $groupedEndpoints): string
data_set($spec, $key, $value);
}
}
return Yaml::dump($spec, 20, 2, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP);
return Yaml::dump($spec, 20, 2, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE | Yaml::DUMP_OBJECT_AS_MAP | Yaml::DUMP_NUMERIC_KEY_AS_STRING);
}

protected function performFinalTasksForLaravelType(): void
Expand Down Expand Up @@ -220,9 +220,9 @@ public function writeExternalHtmlDocs(): void
$writer = app()->makeWith(ExternalHtmlWriter::class, ['config' => $this->config]);
$writer->generate([], $this->paths->intermediateOutputPath(), $this->staticTypeOutputPath);

if (!$this->isStatic) {
$this->performFinalTasksForLaravelType();
}
if (!$this->isStatic) {
$this->performFinalTasksForLaravelType();
}

if ($this->isStatic) {
$outputPath = rtrim($this->staticTypeOutputPath, '/') . '/';
Expand Down Expand Up @@ -252,7 +252,7 @@ protected function getLaravelTypeOutputPath(): ?string
return config(
'view.paths.0',
function_exists('base_path') ? base_path("resources/views") : "resources/views"
). "/" . $this->paths->outputPath();
) . "/" . $this->paths->outputPath();
}

/**
Expand Down
Loading