futurfuturfuturfutur/duckduckduck

Laravel package able to auto generate API documentation through tests, without garbage comments inside the code base.

1.0.3 2021-07-17 11:45 UTC

Requires

• illuminate/support: ^7.0|^8.0

Requires (Dev)

• orchestra/testbench: ^6.0

MIT

• futurfuturfuturfutur

• laravel

README

Laravel package able to auto generate API documentation through tests, without garbage comments inside the code base.

Support of documentations

1. OpenAPI 3.0.0

How it works

If your project has excellent feature testing coverage, it means you already has documentation for this project. You've already described available paths, requests body, parameters, content types, response payloads and http codes. You shouldn't describe it again by your own just in format of the api documentation you use.The package principle is super simple: when you run tests, package middleware just grab response and request of the test case and saves it as an api documentation config file, which you can use to render.

Install

1. Install package with composer require --dev futurfuturfuturfutur/duckduckduck
2. Publish and setup package with php artisan duckduckduck:init. This command will publish duckduckduck.php configuration file inside the config folder of Laravel with base configuration of your API documentation and create /duckduckduck package dir inside the root of the app to contain all documentation configs of your project generated by package.
3. Add TestCase trait inside the phpunit TestCase

   <?php
   
   namespace Tests;
   
   use Futurfuturfuturfutur\Duckduckduck\Traits\DuckduckduckTestCase;
   use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
   
   abstract class TestCase extends BaseTestCase
   {
       use CreatesApplication;
       use DuckduckduckTestCase;
       ...
   }

Usage

Setup

The package will handle most of the things, but some of them you need to define by yourself:

1. Define base info of the API documentation (name, description, type of documentation, version) inside the config/duckduckduck.php
2. Route description and group should be defined as PHPDoc comment of the class of the test (All of them are optional):

   /**
    * @DuckDuckDuckRouteGroup Group name
    * @DuckDuckDuckRouteDescription Description
    */
   class IndexTest extends TestCase
   {

3. A test case description should be defined as PHPDoc comment of the case method:

   /**
    * @DuckDuckDuckRouteDescription Description of the case
    */
   public function testShow()
   {

Run build

Run your tests in API documentation generation mode with php artisan duckduckduck:generate. The package will run feature tests pf your app and generate documentation file inside the package /duckduckduck dir inside the root of the app.

Run documentation render with Docker

The easiest and prettiest way to run your documentation render server to just up the docker container with /duckduckduck package directory passed inside.

Swagger

docker run -p 9999:8080 -e SWAGGER_JSON=/duckduckduck/swagger.json -v /duckduckduck:/duckduckduck swaggerapi/swagger-ui

Remember that mounting duckduckduck folder should be defined as absolute path

API documentation

• Base info about documentation
• Grouped paths with descriptions and methods
• Path, query and body parameters from request
• Responses for the route with payloads and codes
• Info about the server is running the API
• Parameters validation rules from form request

Contributing

Please see Contribution for details.

License

The MIT License (MIT). Please see License File for more information.