Install Swagger UI Documentation for Your PHP RESTful API, Part 3 - #30 

Thanks, I am glad you liked it and got to use it.

Zircote is primary used make PHP play nice with Swagger, the only documentation you would need to set it up is there. The actual notations is Swagger-based. However, even there the documentation is limited but I would start with their sample API: petstore.swagger.io/#/ Once you download Swagger, you can look at the Pet Store sample to see how they have it setup and replicate it for your needs. You can also look through Swagger OAS 3.0 documentation here: swagger.io/specification/ I know this may not be 100% exactly what you were asking about but realistically, there is not "great" documentation for Swagger unless you already know what you are doing with it. Think about it this way, Zircote is a tool on top of Swagger that allows it to work with PHP better, Swagger is the actual documentation tool for your API. Install Zircote, setup your JSON like I did in my video, then do the rest in your methods using Swagger documentation.

Hmm, that must be something related to swagger. It is not part of my code. Can you try to search for a reference to that code and see if you can remove it? If it is a test case it may not be needed.

@@DevDrawer I'm doing same as you explained, but just getting "Warning: Required @OA\Info() not found" and "Warning: Required @OA\PathItem() not found" error when I refresh documention/api :(

Can you post some of your code? I do not know how you have it setup so I don't know what I am looking for. Just a snippet of the area you are having difficulty with.

I am on 8.1 now but when this was made, maybe 7.2 or 7.4.

Hmmm, I am not familiar with Dingo routes but I will take a crack at it. If the index.html text is showing then it sounds like your server is not rendering the file correctly not specifically Laravel or Swagger. Can you send me a screenshot of your setup so I can take a look?

That is good info. Which ever way makes it better for you. I tried it that way and did not like it because I felt it jumbled it up a bit more than how I do it now. I think by adding the comments to the functions and classes, it makes it cleaner for me. It helps me consolidate what I am writing for the documentation and what I am just doing as part of the code and I know where to reference it directly. It also helps with the dynamic build of the JSON/YAML file so developers like you can read the JSON it produces if it is preferrable. Again, this is just a preference for me, everyone can do it their way and mine may not be best but it is preferable to me.

Agree that the annotations makes your code ugly, considering you have your own doc-block definitions as well... Wondering what would be if you do not put the annotations on top of your methods? they doesn't will work? does zircote connects those definitions with your functions?

Glad you liked it.

Sorry for the late response, if you need help with this, maybe try to check and make sure you are loading the correct version of "zircote/swagger-php". You could do "composer require zircote/swagger-php" or "composer updated zircote/swagger-php" in your terminal.

If you have updated it, make sure your reference to the autoload is correctly pointing to the composer autoloader.

Found a way, if anyone wants to use it: " * @OA\Response( * response=200, * description="description", * @OA\JsonContent( * type="object", * example={ * "response": {{"id": "x", * "name": "A", * "desc": "1 letter."}, * * {"id": "Y", * "nome": "B", * "descricao": "2 letter"}} , * } * ) * ), * @OA\Response (response="400", description="Error"), * @OA\Response (response="404", description="Not Found"), "

Thanks for this. I am sure someone will find it useful here.

I am not too familiar with Opis so I do not 1005 know but based on the research I have done on it, it may conflict with Swagger. Opis is a validator that may change the JSON markup to make it validate better and in doing so, may break some of the JSON Swagger uses. Swagger is more just reading what you have for your methods and actions and parsing it into API documentation. Again, I am not too familiar with Opis but that would be my two cents. Good luck.

@@DevDrawer Thanks. I am searching for a way to define "schema" that can be used to validate incoming data (almost always in JSON format) but also in Swagger API as a reference, so I don't have to do the same job twice. Do you have some other recommendation maybe? Best regards

Maybe one of these will help: openapi.tools/#data-validators It looks like none of them work with 3.1, but most have the ability to work with 3.0 and 2.0. I have not personally tested them so I don't 100% know but it may point you in the right direction.

@@DevDrawer Many thanks, I will take a look into it.

You don't have to use Swagger's website to publish your api. You can host it on your own server and it will work the same or you can host it locally and use something like ngrok to create a public tunnel to your local so you can see it but only using the ngrok link you create. I don't use Swagger to host my projects so you don't have to and the tutorial will still work.

Hey I like that idea. I will see what I can do.

for cakephp also plz

If there is an issue with the zircote package, I would try to do a composer update on your production server. If that does not fix it, I would check against the server requirements to make sure that your PHP version is the correct version. Lastly, I would look at the line in the code to see what could be causing the issue. May be a bad copy. I can't help too much with the package as it is not something I developed, but you may be able to search for the error on Zircote's GitHub page. I hope this helps.

So, I have another video (part of another series) that goes over this. The vidoe you are looking for would be here: ru-vid.com/video/%D0%B2%D0%B8%D0%B4%D0%B5%D0%BE-5ujpgk4oe3c.html You can see the full series here: ru-vid.com/video/%D0%B2%D0%B8%D0%B4%D0%B5%D0%BE-OVPPAaFq6Gc.html This full video will go over creating the API and then the JS validation and login events. I hope this helps.

I'm glad you liked it. Stay tuned for more

@@DevDrawer kira tui dai corar moto roisos?

@@variouseducatoinaltube6423 I do not know what you are asking me. Can you ask in English? I tried to translate your text but it does not say anything.

Have you tried to do "composer update" in the command line? Also, look at your composer.json and see if you are requiring a specific version of Swagger.

@@DevDrawer I tried both, everytime it just installs that specific version on its own and I cannot update it

composer why swagger (Yes this is a command)

Glad you like it.

You only need to write it for the endpoints you want to be visible or used on the documentation. Not every method.

I would start here if you are learning about Swaggers annotations using Zircote: zircote.github.io/swagger-php/guide/annotations.html I hope that helps.

The local server I use is php 7.4, so, yes it should.

No problem

Swagger is the same throughout. In your case, where I am adding it to the functions for the API, you would need to find either the controller or classes you would like to appear in the documentation and add the Swagger comments. Then you can point the front end to that folder and it should work. I do not really use Cake PHP so I cannot tell you specifically where to put it, but the process should be the same as long as you are referencing the folder where you are adding the comments to on the front end.

@@DevDrawer ok thank you for your response. This code I tried in my application and i have an error on openApi. Call us undefined openApi/scan(). Shall i install something for openApi. My application php version is PHP 5.6.

@@prabhakarans3033 What version of Zircote are you on? You may have to update to v3.*

@@DevDrawer can you please tell how to update

@@prabhakarans3033 In your composer.json file, look at the version of Zircote you are using. If it is not 3.*, change it to the newest version (3.1.0), save the file, then do a composer update to get the new files. Here are directions from Zircote: zircote.github.io/swagger-php/Migrating-to-v3.html#the-default-output-changed-from-json-to-yaml