CODEWITHSUNDEEP
phpswaggerdocumentation-generation
Skytiger
Skytiger

Reputation: 1845

Setting up Swagger in an existing PHP project

(Please bear with me, I've never set up something like this so I'm feeling my way in the dark)

I've watched some videos and read the documentation on installing swagger-php that I found here, and am trying to set up a basic bit of documentation.

I've created api.php in /application/modules/apiv1/documentation:

<?php
require("library/vendor/autoload.php");
$openapi = \OpenApi\Generator::scan($_SERVER['DOCUMENT_ROOT'] . '/modules/apiv1/controllers');
header('Content-Type: application/json');
echo $openapi->toJson();

and have a controller (LocationController) inside /application/modules/apiv1/controllers. One of the controller actions, that I'm using as my test dummy, is

/**
 * @OA\Get(
 *     path="/modules/apiv1/controllers/location/get",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
public function getAction()
{...}

What I'm trying to do next is to actually view the generated documentation on my local environment, but I have no idea how to view it, so the question is: Is there more setup for me to do to be able to view it? I've done the composer install shown on the zircote github: composer global require zircote/swagger-php but am not sure what my next step is, and I can't seem to find any "How to set up swagger for dummies" stuff, etc

Upvotes: 5

Views: 12701

Answers (2)

Noah
Noah

Reputation: 810

swagger-php generates a JSON file that you can either convert to YAML or keep in JSON. This file is an OpenAPI description document that you can use with any compliant viewer. More about the OpenAPI standard/format can be read here.

The most common one is swagger-ui which can be used locally or in the cloud (by uploading your definition document). There are others such as stoplight which is cloud-based.

The link provided in the answer below (here) actually provides a good explaination on how to get swagger-ui running if you are not at ease with the JavaScript ecosystem.

Upvotes: 4

Şahin Ersever
Şahin Ersever

Reputation: 356

  • Download Swagger-Php Using Composer
  • Add Annotations to Generate Documentation
  • Generate Swagger JSON File
  • Download Swagger-UI Package to your Project
  • Connect Swagger-UI To Your Code

More info in this link.

Upvotes: 1

Related Questions