README

通过面向对象的PHP生成各种规范（例如Swagger规范2.0），与您的实际代码完美同步！

简介

这个库旨在促进创建以结构化数据格式（如JSON、XML、YML）编写的配置和规范。这些文件不仅可以非常长，而且很容易在维护方面变成噩梦。例如，让我们看一下 Swagger 2.0 规范：只有一个资源的手册的API文档可以很容易地超过一千行。这就是为什么需要巨大的努力来获得对文档的良好概述。

另一个问题是，随着时间的推移，实时软件及其规范通常会彼此分离，因为维护人员太忙/疏忽/健忘，无法同步它们。Woohoo Labs. Spec Generator试图缩短它们之间的差距：主要思想是从您的应用程序代码直接生成支持辉煌的面向对象特性的文档！

当谈到创建文档时，您可能会问手动编写这些文档的目的是什么，当其中一些（例如Swagger文档）可以通过使用注解进行定义的框架生成时。虽然这是一个合理的观点，但这种方法（称为反向工程）还有一些主要缺点。

• 这不是向前工程：有时您需要在发货之前设计某些东西 :)
• 您的规范/文档将会是零散的：不会有一个地方可以查找这些定义。这就是为什么如果需要在多个地方更改某些内容，那么这不会很容易。
• 您不会从PHP的能力中受益：您不能扩展类，不能从文件或常量中读取数据，甚至不能从您的IDE中获得代码完成等功能。这削弱了真正的一致性。

特性

• 支持Swagger 2.0 API文档
• 不同的输出格式（数组、JSON、XML、YML）
• 规范可以缓存以提高性能

基本用法

高级用法

缓存

use Doctrine\Common\Cache\MemcachedCache;
use WoohooLabs\SpecGenerator\Swagger2\SwaggerSpec;
use WoohooLabs\SpecGenerator\Swagger2\Info\Contact;
use WoohooLabs\SpecGenerator\Swagger2\Info\MitLicense;

$memcached = new \Memcached();
$memcached->addServer("localhost", 11211);
$cache = new MemcachedCache();
$cache->setMemcached($memcached);

SwaggerSpec::getSpecification(
    function(SwaggerSpec $swagger) {
        $info= Info::create()
            ->setTitle("API Title")
            ->setVersion("1.0.0")
            ->setDescription("API Description")
            ->setContact(new Contact("Sam Support", "123-456-789", "samsupport@example.com"))
            ->setLicense(new MitLicense())
        ;
    
        return $swagger
            ->setInfo($info)
            ->setBasePath("/")
            ->setConsumes(["application/json"])
            ->setSchemes(["http"])
            ->setProduces(["application/vnd.hal+json"])
            ->generate();
    },
    $cache     
);

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。