Take a look at the previous videos in this series: Use PHP to build your own API: th-cam.com/video/oylDnIIYiXU/w-d-xo.html Use Postman to check your API: th-cam.com/video/1g-mFGECt3g/w-d-xo.html
My hosting server don't support composer....but finally I did it manually...installed to my local pc and uploaded files to hosting server using FTP. It is great tutorial how to use Rest API with Swagger and token in PHP.
@@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.
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?
Hi, I'm thinking of using the tool to document a REST API. Where can I find documentation about the notation? (I have found some information in the zircote/swagger-php repository, but it is little and it is not organized) Thanks and sorry for my English
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.
Hi, thanks for this great learning. I'm getting "Uncaught Error: Class 'PHPUnit\Framework\TestCase' not found" error after installing swagger-php and can't pass from this stage. is there any solution?
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 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.
Great video. However, can't make it work for my project. I am using Dingo routes and getting 404 if I navigate to swagger documentation files even after adding API routes for swagger. The postman finds the path but renders the index.html as text.
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?
Hello! How do I add examples on the responses part? Searched for a while but didn't find any good explanation or guide. Thanks for the help! *Edit: found how on responses.
Nice tutorial ! it works like a charm to my local dev. But when i tried to put my project on my live test server ,it gives me error regarding to this line Parse error: syntax error, unexpected '=' in ....... \vendor\zircote\swagger-php\src\StaticAnalyser.php on line 261 I hope you can help me to solve this issue thanks :)
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: th-cam.com/video/5ujpgk4oe3c/w-d-xo.html You can see the full series here: th-cam.com/video/OVPPAaFq6Gc/w-d-xo.html This full video will go over creating the API and then the JS validation and login events. I hope this helps.
Hello ! thanks for your great videos ! I have only one question.. Doing like you did.. is it a public projet in swagger.. or private ? Because if i want to create a new API on Swagger website.. they ask me if i want private or public API.. and private API is for pais members ! So i don't want my api are public ! Thanks so much !
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.
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.
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.
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.
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 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
Take a look at the previous videos in this series:
Use PHP to build your own API: th-cam.com/video/oylDnIIYiXU/w-d-xo.html
Use Postman to check your API: th-cam.com/video/1g-mFGECt3g/w-d-xo.html
My hosting server don't support composer....but finally I did it manually...installed to my local pc and uploaded files to hosting server using FTP. It is great tutorial how to use Rest API with Swagger and token in PHP.
Thanks, I am glad you liked it and got to use it.
Great tutorial! thanks
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.
Thanks a lot. You saved my time.
Glad you liked it.
I would recommend writing docs manually in a separate file with JSON/YAML otherwise it can be quite the visual debt.
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?
I hope there will be a tutorial for this using Laravel.
Hey I like that idea. I will see what I can do.
for cakephp also plz
Hi, I'm thinking of using the tool to document a REST API. Where can I find documentation about the notation? (I have found some information in the zircote/swagger-php repository, but it is little and it is not organized)
Thanks and sorry for my English
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.
Hi, thanks for this great learning. I'm getting "Uncaught Error: Class 'PHPUnit\Framework\TestCase' not found" error after installing swagger-php and can't pass from this stage. is there any solution?
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.
good video... thank you
Glad you like it.
Great content - thank you. One question: is it possible to use Opis Json Schema with Swagger-PHP?
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.
Great video. However, can't make it work for my project. I am using Dingo routes and getting 404 if I navigate to swagger documentation files even after adding API routes for swagger. The postman finds the path but renders the index.html as text.
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?
Hello! How do I add examples on the responses part? Searched for a while but didn't find any good explanation or guide. Thanks for the help!
*Edit: found how on responses.
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.
Thanks
No problem
Nice tutorial ! it works like a charm to my local dev. But when i tried to put my project on my live test server ,it gives me error regarding to this line
Parse error: syntax error, unexpected '=' in ....... \vendor\zircote\swagger-php\src\StaticAnalyser.php on line 261
I hope you can help me to solve this issue thanks :)
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.
Hey man! Awesome work!
How, or, where can I find more instructions on how to set up a login method?
Thanks!
So, I have another video (part of another series) that goes over this. The vidoe you are looking for would be here: th-cam.com/video/5ujpgk4oe3c/w-d-xo.html
You can see the full series here: th-cam.com/video/OVPPAaFq6Gc/w-d-xo.html
This full video will go over creating the API and then the JS validation and login events. I hope this helps.
Hello !
thanks for your great videos ! I have only one question..
Doing like you did.. is it a public projet in swagger.. or private ?
Because if i want to create a new API on Swagger website.. they ask me if i want private or public API.. and private API is for pais members !
So i don't want my api are public ! Thanks so much !
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.
Hello, i use php 8.1 and it seems scan function does not work it always return
{
"openapi": "3.0.0"
},
which version of php are you using?
I am on 8.1 now but when this was made, maybe 7.2 or 7.4.
Hi!
Im having some issues with this; it got this error :
Fatal error: Uncaught Error: Call to undefined function OpenApi\scan()
Any advice ?
Thnx
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.
each time I have to write notations and request for every method ?
You only need to write it for the endpoints you want to be visible or used on the documentation. Not every method.
Why wouldn't composer install any Swagger version higher than 2.0 on my system?
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)
how to find info how to use those annotations?
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.
It works in php >= 5.6?
The local server I use is php 7.4, so, yes it should.
How can i add this in cake php version 2.4.3
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