added some docs and a reader class

cebe · cebe · commit 1820daf78a72 · 2018-10-23T16:12:56.000+02:00
diff --git a/README.md b/README.md
@@ -1,2 +1,81 @@
 # php-openapi
-READ OpenAPI yaml files and make the content accessable in PHP objects.
+
+READ OpenAPI yaml and json files and make the content accessable in PHP objects.
+
+## Install
+
+    composer require cebe/php-openapi
+
+## Requirements
+
+- PHP 7.0 or higher
+
+## Usage
+
+Read OpenAPI spec from JSON:
+
+```php
+use cebe\openapi\Reader;
+
+$openapi = Reader::readFromJson(file_get_contents('openapi.json'));
+```
+
+Read OpenAPI spec from YAML:
+
+```php
+use cebe\openapi\Reader;
+
+$openapi = Reader::readFromYaml(file_get_contents('openapi.yaml'));
+```
+
+Access specification data:
+
+```php
+echo $openapi->openapi; // openAPI version, e.g. 3.0.0
+echo $openapi->info->title; // API title
+foreach($openapi->paths as $path => $definition) {
+    // iterate path definitions
+}
+```
+
+Object properties are exactly like in the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#openapi-specification).
+You may also access additional properties added by specification extensions.
+
+
+## Completeness
+
+This library is currently work in progress, the following list tracks completeness:
+
+- [ ] read OpenAPI 3.0 JSON
+- [ ] read OpenAPI 3.0 YAML
+- [ ] OpenAPI 3.0 Schema
+  - [x] OpenAPI Object
+  - [x] Info Object
+  - [x] Contact Object
+  - [x] License Object
+  - [x] Server Object
+  - [x] Server Variable Object
+  - [ ] Components Object
+  - [ ] Paths Object
+  - [ ] Path Item Object
+  - [ ] Operation Object
+  - [x] External Documentation Object
+  - [ ] Parameter Object
+  - [ ] Request Body Object
+  - [ ] Media Type Object
+  - [ ] Encoding Object
+  - [ ] Responses Object
+  - [ ] Response Object
+  - [ ] Callback Object
+  - [ ] Example Object
+  - [ ] Link Object
+  - [ ] Header Object
+  - [ ] Tag Object
+  - [ ] Reference Object
+  - [ ] Schema Object
+  - [ ] Discriminator Object
+  - [ ] XML Object
+  - [ ] Security Scheme Object
+  - [ ] OAuth Flows Object
+  - [ ] OAuth Flow Object
+  - [ ] Security Requirement Object
diff --git a/src/Reader.php b/src/Reader.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace cebe\openapi;
+
+use cebe\openapi\spec\OpenApi;
+use cebe\openapi\spec\SpecBaseObject;
+use Symfony\Component\Yaml\Yaml;
+
+/**
+ *
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ */
+class Reader
+{
+    public static function readFromJson(string $json, string $baseType = OpenApi::class): SpecBaseObject
+    {
+        return new $baseType(json_decode($json, true));
+    }
+
+    public static function readFromYaml(string $yaml, string $baseType = OpenApi::class): SpecBaseObject
+    {
+        return new $baseType(Yaml::parse($yaml));
+    }
+}
diff --git a/tests/ReaderTest.php b/tests/ReaderTest.php
@@ -0,0 +1,56 @@
+<?php
+
+/**
+ *
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ */
+class ReaderTest extends \PHPUnit\Framework\TestCase
+{
+    public function testReadJson()
+    {
+        $openapi = \cebe\openapi\Reader::readFromJson(<<<JSON
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Test API",
+    "version": "1.0.0"
+  },
+  "paths": {
+
+  }
+}
+JSON
+        );
+
+        $this->assertApiContent($openapi);
+    }
+
+    public function testReadYaml()
+    {
+        $openapi = \cebe\openapi\Reader::readFromYaml(<<<YAML
+openapi: 3.0.0
+info:
+  title: "Test API"
+  version: "1.0.0"
+paths:
+  /somepath:
+YAML
+        );
+
+        $this->assertApiContent($openapi);
+    }
+
+    private function assertApiContent(\cebe\openapi\spec\OpenApi $openapi)
+    {
+        $result = $openapi->validate();
+        $this->assertEquals([], $openapi->getErrors());
+        $this->assertTrue($result);
+
+
+        $this->assertEquals("3.0.0", $openapi->openapi);
+        $this->assertEquals("Test API", $openapi->info->title);
+        $this->assertEquals("1.0.0", $openapi->info->version);
+    }
+
+}
diff --git a/tests/spec/OpenApiTest.php b/tests/spec/OpenApiTest.php
@@ -41,6 +41,7 @@ public function testReadPetStore()
         $this->assertEquals("Swagger Petstore", $openapi->info->title);
         // info.license
         $this->assertInstanceOf(\cebe\openapi\spec\License::class, $openapi->info->license);
+        $this->assertEquals("MIT", $openapi->info->license->name);
         // info.contact
         $this->assertNull($openapi->info->contact);
 
@@ -50,17 +51,8 @@ public function testReadPetStore()
         $this->assertCount(1, $openapi->servers);
         foreach ($openapi->servers as $server) {
             $this->assertInstanceOf(\cebe\openapi\spec\Server::class, $server);
+            $this->assertEquals("http://petstore.swagger.io/v1", $server->url);
 
         }
-
-        /*
-        openapi: "3.0.0"
-        info:
-          version: 1.0.0
-          title: Swagger Petstore
-          license:
-            name: MIT
-        servers:
-          - url: http://petstore.swagger.io/v1*/
     }
 }
