From 789b0869d5ef219a8fbc60b0a5bc0ad39cb57b5a Mon Sep 17 00:00:00 2001
From: "Pedro J. Molina" <pjmolina@metadev.pro>
Date: Mon, 10 Jun 2024 16:46:58 +0200
Subject: [PATCH 1/2] Initial docs. issue #75

---
 README.md     |  7 +++--
 docs/index.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 3 deletions(-)
 create mode 100644 docs/index.md

diff --git a/README.md b/README.md
index b72422f..12f647d 100644
--- a/README.md
+++ b/README.md
@@ -51,9 +51,10 @@ Install package via **npm**:
 npm i --save openapi3-ts
 ```
 
-## Versions and Changelog
+## Documentation, Versions, and Changelog
 
-See [changelog](Changelog.md).
+* [Documentation](docs/index.md).
+* See [changelog](Changelog.md) for version and changes.
 
 ## References
 
@@ -67,4 +68,4 @@ Licensed under the MIT License.
 
 **Contact:** Pedro J. Molina | github: [pjmolina](https://github.com/pjmolina) | twitter: [pmolinam](https://twitter.com/pmolinam)
 
-(c) 2017-2023. [Pedro J. Molina](http://pjmolina.com) at Metadev S.L. [https://metadev.pro](https://metadev.pro) & contributors.
+(c) 2017-2024. [Pedro J. Molina](http://pjmolina.com) at Metadev S.L. [https://metadev.pro](https://metadev.pro) & contributors.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..a9703ba
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,79 @@
+# OpenAPI3-TS Documentation
+
+OpenAPI3-TS is a library implemented in TypeScript to help creating documents following the [**OpenAPI Specifications**](https://spec.openapis.org/oas/latest.html) to describe REST APIs in a machine & humam processable format.
+
+## Use Cases
+
+1. Create a OAS document from scratch and export it to JSON or YAML.
+
+The builder pattern, the TS compiler & the code-completion will guide you to add the correct data.
+
+- I can be used in TypeScript or Javascript projects working with NodeJS or Deno (in the backend).
+- But also on the browser as the libraries has not dependencies on other libs.
+
+## Basic Example
+
+Minimal example to generate a 3.1 OAS compliant document:
+
+```typescript
+import * from 'openapi3-ts/oas31';
+
+function buildOas() {
+    const builder = OpenApiBuilder
+        .create()
+        .addOpenApiVersion('3.1.0')
+        .addInfo({
+          title: 'app',
+          version: 'version'
+        })
+        .addLicense({
+          name: 'Apache 2.0',
+          url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+        }),
+        .addTitle('my title')
+        .addPath('pet/{petId}', {
+          get: {
+            tags: ["pet"],
+            summary: "Find pet by ID",
+            description: "Returns a single pet",
+            operationId: "getPetById",
+            produces: ["application/json", "application/xml"]
+          }
+        })
+        .addResponse('Created', {
+          description: 'Object created'
+        })
+        .addSchema('Email', {
+          type: 'string',
+          format: 'email'
+        })
+        .addParameter('id',  {
+          name: 'id',
+          in: 'header' as ParameterLocation,
+          schema: {
+            $ref: '#/components/schemas/id'
+        });
+    //...keep building
+
+    const doc = builder.getSpec();
+    const docJson = builder.getSpecAsJson();
+    const docYaml = builder.getSpecAsYaml();
+}
+
+```
+
+## Dependencies
+
+The unique dependency in runtime is `yaml` to provide the YAML from/to conversions features.
+
+## Code Organization
+
+- `src` contains the production code.
+  - `dsl` provides the API of the library following the [intenal DSL style](https://martinfowler.com/bliki/InternalDslStyle.html) (or _fluent interface_) with two flavours: 3.0.x & 3.1.x to allow conformance with both versions of the spec.
+  - `model` provides a DOM (Document Object Model) describing the concepts defined in the OpenAPI spec. Again in two flavours: 3.0.x and 3.1.x.
+  - Finally `oas30.ts` & `oas31.ts` expose the types as separate namespaces.
+- `test` constains the unit tests.
+
+## License
+
+Licensed under the MIT License.

From 676e7c34c9ab88fc3ec50d4631741cc051766eda Mon Sep 17 00:00:00 2001
From: "Pedro J. Molina" <pjmolina@metadev.pro>
Date: Mon, 10 Jun 2024 16:51:25 +0200
Subject: [PATCH 2/2] xor

---
 docs/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/index.md b/docs/index.md
index a9703ba..4c0c298 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -16,7 +16,7 @@ The builder pattern, the TS compiler & the code-completion will guide you to add
 Minimal example to generate a 3.1 OAS compliant document:
 
 ```typescript
-import * from 'openapi3-ts/oas31';
+import * from 'openapi3-ts/oas31'; // Pick `openapi3-ts/oas31` for 3.1.x (x)or pick `openapi3-ts/oas30` for 3.0.x
 
 function buildOas() {
     const builder = OpenApiBuilder