Background: I have installed composer installed zircote/swagger-php and have installed openapi-generator-cli with apt-get.
I am not sure whether or not I am attempting to use these tools correctly, however I've been unable to find documentation pointing me in any direction.
I have a controller file with a whole bunch of code in it. I want to test whether or not I can generate a json file from it using open api annotation.
Here's a sample of my code (I've cut out unrelated chunks of it):
<?php
/**
* #OA\Info(title="My First API", version="0.1")
*/
class Apiv1_LocationController extends App_Controller_API
{
/* Publicly exposed attributes and the field type for filtering */
protected $_exported = array('id','created','modified','name','address','phone','external_id','postcode','country','timezone','date_format','lacps','staff_count');
protected $_schematypes = array(
'string' => ['name','address','phone','external_id','postcode','country','timezone','date_format'],
'int' => ['id','staff_count'],
'timestamp' => ['created','modified'],
'complex'=> ['lacps'],
);
{more unrelated code...}
/**
* #OA\Get(
* path="/api/resource.json",
* #OA\Response(response="200", description="An example resource")
* )
*/
public function getAction()
{
{code inside action...}
}
}
The cli command I use:
openapi-generator-cli generate -g php -i <path_to_LocationController>
I get the following error:
[main] INFO o.o.c.ignore.CodegenIgnoreProcessor - No .openapi-generator-ignore file found.
Exception in thread "main" java.lang.RuntimeException: Issues with the OpenAPI input. Possible causes: invalid/missing spec, malformed JSON/YAML files, etc.
This leads me to believe I am using the openapi-generator-cli tool incorrectly, since I wouldn't be expecting to need a JSON or YAML file, I am trying to generate that file.
I'll keep trying, but if someone could help me realized what I'm doing wrong or how I'm misunderstanding the tool, I'd really appreciate it.
So I realized I'd been going about this in entirely the wrong way.
I used the zircote/swagger-php library to generate the JSON file I required with the following command (In the directory where I wanted the JSON to be generated):
./<path_to_vendor_directory>/vendor/zircote/swagger-php/bin/openapi --pattern "*Controller.php" --output <name_of_file>.json --format json <location_to_search_from_recursively>
Related
I'm Problems Using Doctrine does not Jelastic .
Displays the Problem:
"Warning: require_once ( /vendor/doctrine/orm/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php " ) : failed to open stream : No such file or directory in /var/www/webroot/ROOT/vendor/doctrine/annotations/lib/Doctrine/Common/Annotations/AnnotationRegistry.php on line 64 Fatal error: require_once (): Failed opening require ' /vendor/doctrine/orm/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php ' ( include_path = ' .: / usr / share / pear ' ) in /var/www/webroot/ROOT/vendor/doctrine/annotations/lib/Doctrine/Common/Annotations/AnnotationRegistry.php the line 64 .
Following url problem: http://temprafesta.jelasticls.com.br/
I have already installed the ZF2 + Composer via SSH and its dependencies. Occurred with success , but when I make an appointment with the Doctrine presents this error.
Could anyone help ?
Kind Regards,
Allan .
From the given error it's clear that the base path is not taken into account. Likely it's a bug in Doctrine. Have you been able to check out another version of Doctrine?
Well, the file that emits that error is this one:
https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/AnnotationRegistry.php#L64
/**
* Registers file.
*
* #param string $file
*
* #return void
*/
static public function registerFile($file)
{
require_once $file;
}
I dont't know why someone would want to call this method, but there's only two scenarios: It's either Doctrine's code internally, or it's your code.
I've not found too many places where doctrine calls this function, but this one sounds like it's it:
https://github.com/doctrine/doctrine2/blob/664b6bf4c52c893011ec4b7b3c99e94399ed0316/lib/Doctrine/ORM/Configuration.php#L153
Now the question is: Why is __DIR__ being evaluated to /vendor/doctrine/orm/lib/Doctrine/ORM there? It doesn't make sense, unless PHP gets confused because of any fancy filesystem stuff. I'd recommend diving into this part and add some debug output there just to be sure everything works as expected there. I think it doesn't.
I am trying to make the Restful API documentation in PHP swagger, what I did before is that I changed the JSON to work out, now I know we can make the JSON by making PHP files and using swagger notation. I did check the Pet.php example and I get the code but I don't know how to execute the file to get the JSON API documentation which I can link with my Swagger UI. I read the documentation but it is so confusing and I don't know how to get through this problem can anyone help, please? Here is the link I study but to no worth.
https://github.com/zircote/swagger-php
Swagger-PHP for generating JSON file for Swagger-UI
Can anyone tell me step-by-step how to generate the API documentation in JSON? I will be very thankful to him thanks.
There are two way to achieve this in swagger-php 2.0.
I.
The first solution is to create a controller or script which will generate the documentation on each request. This is a good solution in a development environment where you want to see quickly the outcome of your changes.
Here is an example of a controller which does this.
<?php
namespace Controllers;
use Swagger\Annotations as SWG;
use Swagger;
/**
* #SWG\Swagger(
* basePath="/path/to/opration/",
* produces={"application/json"},
* swagger="2.0",
* #SWG\Info(
* version="1.0.0",
* title="My API"
* )
* )
*
*/
class Documentation {
const API_PATH = "path/to/my/documented/files/";
public function show(){
$swagger = Swagger\scan(self::API_PATH);
return json_enconde($swagger); //you can echo this in the calling script.
}
}
Note: The example above assumes you installed Swagger-php with Composer and that the calling script include the composer generated autoload file (usually called: vendor/autoload.php).
II.
The first solution consisting of generating a static json API documentation is described here: https://stackoverflow.com/a/21380432/2853903
This solution recommended for production deployment, where you would not want to regenerate the documentation on every request.
I created file commands/TestCommand.php in my yii-powered project:
class TestCommand extends CConsoleCommand
{
public function actionIndex()
{
echo "Hello World!\n";
}
}
And it's became visible via yiic:
Yii command runner (based on Yii v1.1.14)
Usage: yiic.php <command-name> [parameters...]
The following commands are available:
- message
- migrate
- shell
- test <<<
- webapp
To see individual command help, use the following:
yiic.php help <command-name>
If I am trying to get some help information about this console command:
php yiic.php help test
I see default text:
Usage: yiic.php test index
How can I write my TestCommand class which will show my help information? Is it a some public field or special method which return help text? I need something like that:
php yiic.php help webapp
Result like I need:
USAGE
yiic webapp <app-path> [<vcs>]
DESCRIPTION
This command generates an Yii Web Application at the specified location.
PARAMETERS
* app-path: required, the directory where the new application will be created.
If the directory does not exist, it will be created. After the application
is created, please make sure the directory can be accessed by Web users.
* vcs: optional, version control system you're going to use in the new project.
Application generator will create all needed files to the specified VCS
(such as .gitignore, .gitkeep, etc.). Possible values: git, hg. Do not
use this argument if you're going to create VCS files yourself.
You can override the default getHelp method to implements your help!
It must return a string that is the help text.
Provides the command description. This method may be overridden to return the actual command description.
Here is the default method:
public function getHelp()
{
$help='Usage: '.$this->getCommandRunner()->getScriptName().' '.$this->getName();
$options=$this->getOptionHelp();
if(empty($options))
return $help."\n";
if(count($options)===1)
return $help.' '.$options[0]."\n";
$help.=" <action>\nActions:\n";
foreach($options as $option)
$help.=' '.$option."\n";
return $help;
}
You can also override the default getOptionHelp method that is called in getHelp
Provides the command option help information. The default implementation will return all available actions together with their corresponding option information.
Source
I've installed phpDoc on our server, set up etc. It's producing documentation correctly.
We're using the 'Responsive' template, however this error occurs regardless of the template used.
Under the 'Errors', each file scanned seems to have the following error:
Type Line Description
error 0 No summary was found for this file
I've googled exhaustively for this, and can't find a solution. I've even gone through the effort of tracking down the server error code behind the message PPC:ERR-50000 and attempting to track back the condition which causes the error, but got a bit lost.
My Question:
What does this error mean? Why is it on line 0, and how the hell do I get rid of it?! Even if I have done the docblock correctly, can I hide this error? My error-free ocd is going crazy!
Many thanks
EDIT
Some extra information: Each of my files have the following docblock from line 1 of the file:
<?php
/**
* Short Description
*
* Long Description
*
* #package Some Package
* #subpackage Some Subpackage
* #category Some Category
* #author F Bloggs <gbloggs#email.com>
*/
?>
But does the top of your file have two such docblocks? The first docblock is expected to be the one for the file itself, and a second docblock should pair up with the first documentable code element that appears after it.
However, if you only have one docblock at the top of the file, it will get paired up with the first code element found, thus the "file itself" will seem to be missing its docblock. That is what that error is supposed to indicate.
#ashnazg is right but I want to improve your answer with an example.
A File-level DocBlock should be the first docblock and must have a Summary (in this example the summary is "Class Category | core/Category.class.php").
Then a Class-level DocBlock is placed before a class definition.
<?php
/**
* Class Category | core/Category.class.php
*
* #package MyApp XYZ
* #subpackage Categories
* #author Sandro Miguel Marques <sandromiguel#something.com>
* #version v.1.1 (06/12/2016)
* #copyright Copyright (c) 2016, Sandro
*/
namespace Myapp;
use \PDO;
use \Exception;
use \PDOException;
/**
* Class Category - active record
*
* Recipe categories
*/
class Category {
...
So after a lot of searching on the server, I have a semi-fix for the problem should anyone else be encountering the same issue.
I've found out how to hide the error from the documentation, but not what is causing it.
If the error you are receiving is on Line 0, and is no summary found for this file, then you will need to edit the following file:
phpDocumentor/src/phpDocumentor/Plugin/Core/Transformer/Writer/xml.php
You will then need to search for the protected method: createErrorEntry()
This is what the existing method looks like:
protected function createErrorEntry($error, $parse_errors)
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
This method needs to have an IF condition added. Wrap the entire body of the method in the following IF condition:
protected function createErrorEntry($error, $parse_errors)
{
if($error->getCode()!=='PPC:ERR-50000')
{
$marker_obj = new \DOMElement(strtolower($error->getSeverity()));
$parse_errors->appendChild($marker_obj);
$message = ($this->getTranslator())
? vsprintf($this->getTranslator()->translate($error->getCode()), $error->getContext())
: $error->getCode();
$marker_obj->appendChild(new \DOMText($message));
$marker_obj->setAttribute('line', $error->getLine());
$marker_obj->setAttribute('code', $error->getCode());
}
}
This will stop the error being recorded, in effect, it hides the error from the end user, it doesn't fix what I can only assume is a bug in phpDocumentor. So the original error still exists, it just hasn't been recorded.
One thing I did note while debugging, is the vsprintf() function produces an error for on the PPC:ERR-50000 error. The vsprintf() produces the error PHP Warning: vsprintf(): Too few arguments. If i find out how to fix the code to stop the false error (or fix the comments to ensure the error isn't given reason to log), I'll post it here.
For what it's worth, I've found that creating the documentation from the commandline using parameters rather than using parameters in :
phpdoc -d ./ -t ./docs --ignore=vendor/*
vs parameters in a phpdoc.dist.xml configuration file has resolved all of the issues raised in this thread.
I don't think this stops the need for two docblocks at the top of files but it does appear to resolve the "No summary was found for this file" error when building the documentation.
I got the same error because I use PHP > 7 and PHPDocumentor did not recognize the syntax, so this "default error" was provided.
In my code, PHPDocumentor isn't able to parse null returns (?) in functions.
I solved this issue going to this link
https://github.com/phpDocumentor/phpDocumentor/releases
I wgot the "PHP-7 Syntax support" and installed it
wget https://github.com/phpDocumentor/phpDocumentor/releases/download/v2.9.0/phpDocumentor.phar
sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
sudo chmod +x /usr/local/bin/phpdoc
check version:
phpdoc --version
= phpDocumentor version v2.9.0
It works with this phpDocumentor version
I got the exact same error message. I got rid of it..
the solution is very simple. in the file block at the
top, the summary line has a period at the end of it. This indicates
its a summary line.
make sure that no other blocks that follow for attributes or methods or whatever have a summary line with a period at the end. Once I removed those, the error disappeared immediately (PHPDocumentor 2.8.5)
I came accross this issue when my site works with php v7.4 while phpDocumentor.phar is started with php v7.2.5 and there where strong typed properties in my class. Strong typed properties aren't allowed before php v7.4.0.
class Template
{
/**
* #var string The template with some replacement strings
*/
private string $template;
....
I was not able to find a good resource which is describing the following Zend_Tool command:
zf create project path name-of-profile file-of-profile
Not even here:
http://framework.zend.com/manual/en/zend.tool.usage.cli.html
Does somebody know a good resource regarding this command?
Note: I'm interested in the name-of-profile and file-of-profile part. Usage, examples, etc.
Maybe even a visual approach like in this references:
http://marklodato.github.com/visual-git-guide/index-en.html
http://osteele.com/archives/2008/05/commit-policies
I am not familiar enough with the internals of ZF Tool Project, but have a look at
http://framework.zend.com/manual/en/zend.tool.project.create-a-project.html
http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Tool/Project/Provider/Project.php
Afaik (which is not much) Zend Tool maintains an XML file to keep track of your project. This is required for any subsequent actions to be applied correctly to your project through Zend Tool.
The DocBlock for the create action in the Project Provider says:
/**
* create()
*
* #param string $path
* #param string $nameOfProfile shortName=n
* #param string $fileOfProfile shortName=f
*/
When run without the two optional arguments, the method will eventually create a new project file with
$newProfile = new Zend_Tool_Project_Profile(array(
'projectDirectory' => $path,
'profileData' => $profileData
));
with $profileDate being the content of the default configuration file. If you specify $fileOfProfile, you can override the configuration file and supply your own file, e.g.
if ($fileOfProfile != null && file_exists($fileOfProfile)) {
$profileData = file_get_contents($fileOfProfile);
}
Obviously, you have to supply a full path to the file for this to work. The alternative is to supply a file identifier, which Zend Tool will then try to find in a predefined location, e.g.
$storage = $this->_registry->getStorage();
if ($profileData == '' && $nameOfProfile != null && $storage->isEnabled()) {
$profileData = $storage->get('project/profiles/' . $nameOfProfile . '.xml');
}
I have no clue what the storage part is about. Like I said, I am not familiar with Zend Tool's inner workings. If I understand correctly, you can use the additional two arguments to load an existing project in a new location or customize the default one.
You might want to browse the ChangeLog to find out more about it.