Setting up Swagger in an existing PHP project

Question

(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

MangledMMU · Accepted Answer · 2021-09-21 05:50:47Z

4

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.

answered Sep 21, 2021 at 5:50

MangledMMU

8221 gold badge10 silver badges29 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Şahin Ersever · Accepted Answer · 2021-09-21 01:25:02Z

1

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

1 Comment

Skytiger Over a year ago

Thanks, I followed the link and attempted to follow the steps set out in it. However, I am having issues currently with use OpenApi\Annotations as OA; - The OpenApi namespace isn't defined. Once I get that issue sorted out I'll continue with that guide.

Collectives™ on Stack Overflow

Setting up Swagger in an existing PHP project

2 Answers 2

Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related