Automatically generate OpenAPI, Swagger, and Redoc documentation from your existing CakePHP code.
Home Page: http://cakephpswaggerbake.cnizz.com/
License: MIT License
Consider @SwagOperation(isVisible=boolean) for hiding operations (controller actions) from swagger ui.
Support schema example: https://swagger.io/docs/specification/data-models/data-types/
Readme will describe how to add an Extension.
Describe the bug
Argument 1 passed to SwaggerBake\Lib\OpenApi\Content::setSchema() must be an instance of SwaggerBake\Lib\OpenApi\Schema, string given, called in /var/www/personal/cakephp-swagger-bake/src/Lib/Annotation/SwagRequestBodyContentHandler.php on line 1
To Reproduce
Add the following to an HTTP POST method:
@Swag\SwagRequestBody(description="my description", required=true, ignoreCakeSchema=true)
@Swag\SwagRequestBodyContent(refEntity="#/components/schemas/Actor", mimeType="application/json")Expected behavior
Expected JSON schema to be accepted
Document using built-in swagger ui template with a userland controller. Verify works and add to README.md
Response type codes of >= 400 and >= 500 can be created by looking at thrown exceptions.
Get 400 level exception types from Cake Exception classes.
Default to 500 if exception type is unknown or generic.
The response type should default to the value defined for responseContentTypes in swagger_bake.php config if only one item is set and no response type was supplied by annotation etc...
Read validation rules from Model/Table classes and define swagger input properties etc from them. For example, swagger forms should know whether a field is required or not.
Currently @throw only displays the exception classes short name in swagger ui. For example:
/**
* Edit method
*
* @param string|null $id Employee id.
* @return \Cake\Http\Response|null|void HTTP 200 on successful edit
* @throws \Cake\Datasource\Exception\RecordNotFoundException When record not found.
*/
Would only display as a 404 with "RecordNotFoundException" as the description. Add in the "When record not found" text to swagger ui.
Parameter properties to be added:
@AbstractParameter annotation properties:
Putting it together:
AbstractParameter is extended by @SwagQuery, @SwagForm, and @SwagHeader. These annotations are used by their respective classes in calls stemming from OperationFromRouteFactory
Related
Describe the bug
When using XML request or response the following error is generated in Swagger UI:
XML example cannot be generated; root element name is undefined
See swagger-api/swagger-ui#4650
To Reproduce
Set swagger_bake.php config to use XML and reload swagger page. Then go to any post/patch or response.
'requestAccepts' => ['application/xml'],
'responseContentTypes' => ['application/xml'],Expected behavior
Renders example without error
Add bake template.
Read a Data Transfer Object (DTO) and optionally set as schema, response schema and/or request schema. To handle as many DTO libraries as possible consider using an Interface. For example:
interface SwaggerBakeDtoInterface
{
public function getSwaggerReadableArray() : array;
}
class MyDto implements SwaggerBakeDtoInterface
{
public function getSwaggerReadableArray() : array
{
return [
'fieldName' => 'string',
];
}
}Need to consider if this will support deep nesting complex data types.
Alternatively. We could accept a DTO class as an annotation argument and parse that for Doc Block comments:
/**
* @Swag\DataTransferObject(class="\App\Dto\MyDto")
*/
public function index() {}/**@var string $my_var description of this attribute*/
private $my_varRight now, the definitions in config/swagger.yml override the ones in PHP doc block. It will be great to merge those so that documentation based detail can remain in doc block and overrides can be defined in the yml file.
Currently, the Controller name is being used for the tags attribute. As you suggested, can you please add @SwagTag(name="myTag") to override the default?
Potential solution: Class level annotation on controllers such as @SwagIgnore or @SwagPath
/**
* @SwagIgnore
* @SwagPath(isVsible=false)
*/
class FooController
{
...Create annotation to support https://crud-json-api.readthedocs.io/en/latest/api-usage-advanced/sorting.html
Schema Property properties to be added:
@SwagEntityAttribute annotation properties:
Unit Tests:
Misc:
Might need to have @SwagForm not extend from AbstractParameter since its actually a schema property.
Placeholder for now.
SwaggerBack needs to instantiate controllers for doctrine/annotations to parse @Swag annotations and phpdocumentor/reflection-docblock to parse PHP doc blocks.
To do this, SwaggerBake iterates over the namespaces.controllers configuration array until it can find the controller. It does this in a few different places. This kind of hacky.
It should be possible to use the data in RouteDecorator and the configured route prefix for routes.php to instantiate the class. Scenarios to account for are controllers in:
Unit tests don't exist for these scenarios, they will need to be built first before a refactor can begin.
Need to convert demo over to https://github.com/cnizzardini/cakephp-sakila for more verbose example and testing.
Updated code in 1.4.0 to use ValidationSet::isPresenceRequired instead.
Describe the bug
components > schemas > NAME > type is not being set properly. object becomes 1.
To Reproduce
components:
schemas:
Exception:
type: object
properties:
code:
type: integer
example: 500
url:
type: string
example: /url/path
message:
type: string
example: Internal Error
Expected behavior
type object should remain as object.
Include an entity via an annotation such as @SwagEntity, example:
/**
* Employee Entity
*
* @SwagEntity(isVisibile=bool)
*/
class Employee extends Entity
{
...
This will allow a user to:
Describe the bug
Swagger does not support decimal, float, uuid, or text. These need to be converted.
To Reproduce
Expected behavior
No errors.
Path properties to be added:
@SwagPath annotation properties:
Putting it together:
Path properties from @SwagPath annotations in PathFromRouteFactoryhttps://docs.google.com/spreadsheets/d/e/2PACX-1vRTWE7nsTouFdHZsG6OKlZ-1lHeJGI0wqNlRVEgiG4eCFY0dMxkBLaw313mU_a73U7emoRdFcGPUq94/pubhtml
https://swagger.io/specification/
Add annotation @SwagProperty
Example:
/**
* @SwagProperty(name="string", readOnly=boo, writeOnly=bool, type="string")
*/Support defining oneOf, anyOf, and allOf through swagger.yml
SchemaProperty::format is an open value per the OpenApi specification and thus can be anything. https://swagger.io/docs/specification/data-models/data-types/?sbsearch=Data%20Format
Use the CakePHP Validator to set additional formats such as latitude, longitude, lat/lng, email etc...
This will likely be a new class in SwaggerBake\Lib\Schema similar to SchemaPropertyValidation.
Validator::lengthBetween() should translate to minLength and maxLength in SwaggerBake\Lib\Schema\SchemaPropertyValidation
Console commands don't have any unit tests. Refactor of testing and/or commands may be needed to make them testable.
OpenAPI Specification for Schema:enum https://swagger.io/docs/specification/describing-parameters/
Describe the bug
Redocly/redoc#1261
To Reproduce
Steps to reproduce the behavior:
Expected behavior
Redoc loads
SwagOperation(useSchema=bool)
Default = true, but setting to false will ignore schema. Might want to combine with #7
Currently always need to define @SwagEntityAttribute to tell SwaggerBake created and modified should be read only. These should automatically be set as read only.
Schema is only referenced by paths if the path is a core rest action: index, view, create, edit, and delete. Create a new annotation to force a reference in the response schema.
@SwagResponseSchema(refEntity="string")
See also #13
Roadmap for supporting full OpenApi 3.x schema is available here:
Blue-text in YAML or Code columns indicates how the feature will be implemented in future versions. The non-blue text indicates how the feature is currently implemented.
Schema properties to be added:
@SwagEntity annotation properties:
Putting it together:
Schema properties from @SwagEntity annotations in SchemaFactoryRelated
See https://swagger.io/docs/specification/describing-responses/
Change SwagResponseSchema::httpCode to string from integer
Verify support for ranged response codes
Use h() function to cleanse user input
Public demo project available on github and on a public web server showing usage.
Use AuthenticationComponent to set Operation::security.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.