refactor documents (#121)

2024-03-18 14:54:37 +03:00 · 2020-04-28 01:29:19 +09:00
parent 76043419f3
commit 0f015604c9
9 changed files with 716 additions and 122 deletions
--- a/README.md
+++ b/README.md
@@ -8,8 +8,8 @@ This code generator creates pydantic model from an openapi file and others.
 [![codecov](https://codecov.io/gh/koxudaxi/datamodel-code-generator/branch/master/graph/badge.svg)](https://codecov.io/gh/koxudaxi/datamodel-code-generator)
 ![license](https://img.shields.io/github/license/koxudaxi/datamodel-code-generator.svg)

-
-## This project is an experimental phase.
+## Help
+See [documentation](https://koxudaxi.github.io/datamodel-code-generator) for more details.


 ## Supported file formats
@@ -80,30 +80,6 @@ optional arguments:
  --version             show version
 ```

-## Formatting
-
-Code generated by `datamodel-codegen` will be passed through `isort` and
-`black` to produce consistent, well-formatted results. Settings for these tools
-can be specified in `pyproject.toml` (located in the output directory, or in
-some parent of the output directory).
-
-Example `pyproject.toml`:
-```toml
-[tool.black]
-skip-string-normalization = true
-line-length = 100
-
-[tool.isort]
-multi_line_output = 3
-include_trailing_comma = true
-force_grid_wrap = 0
-use_parentheses = true
-line_length = 100
-known_first_party = "kelvin"
-```
-
-See the [Black Project](https://black.readthedocs.io/en/stable/pyproject_toml.html) for more information.
-
 ## Example
 ### OpenAPI
 ```sh
@@ -313,105 +289,14 @@ class apis(BaseModel):
    __root__: List[api]
 ```

-### Json Data
-```sh
-$ datamodel-codegen  --input data.json --input-file-type json --output model.py
-```
-
-`data.json`:
-```json
-{
-  "pets": [
-    {
-      "name": "dog", 
-      "age": 3
-    }, 
-    {
-      "name": "cat", 
-      "age": 1
-    }
-  ],
-  "version": "1.0.2"
-}
-```
-
-
-`model.py`:
-```
-# generated by datamodel-codegen:
-#   filename:  data.json
-#   timestamp: 2020-04-15T15:35:20+00:00
-
-from __future__ import annotations
-
-from typing import List
-
-from pydantic import BaseModel
-
-
-class Pet(BaseModel):
-    name: str
-    age: int
-
-
-class Model(BaseModel):
-    pets: List[Pet]
-    version: str
-
-
-```
-## Development
-
-Install the package in editable mode:
-
-```sh
-$ git clone git@github.com:koxudaxi/datamodel-code-generator.git
-$ pip install -e datamodel-code-generator
-```
-
-## Contribute
-We are waiting for your contributions to `datamodel-code-generator`.
-
-### How to contribute
-```shell script
-## 1. Clone your fork repository
-$ git clone git@github.com:<your username>/datamodel-code-generator.git
-$ cd datamodel-code-generator
-
-## 2. Create `venv` with python3.7 (also you should do with python3.6)
-$ python3.7 -m venv venv37
-$ source venv37/bin/activate  
-
-## 3. Install dependencies
-$ python3 -m pip install ".[all]" 
-
-## 4. Create new branch and rewrite code.
-$ git checkout -b new-branch
-
-## 5. Run unittest (you should pass all test and coverage should be 100%)
-$ ./scripts/test.sh
-
-## 6. Format code
-$ ./scripts/format.sh
-
-## 7. Check lint (mypy)
-$ ./scripts/lint.sh
-
-## 8. Commit and Push...
-```

 ## PyPi 

 [https://pypi.org/project/datamodel-code-generator](https://pypi.org/project/datamodel-code-generator)

-## Source Code
-
-[https://github.com/koxudaxi/datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator)
-
-## Documentation
-
-[https://koxudaxi.github.io/datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator)
-
 ## License

 datamodel-code-generator is released under the MIT License. http://www.opensource.org/licenses/mit-license
+
+
+## This project is an experimental phase.
--- a/docs/development-contributing.md
+++ b/docs/development-contributing.md
@@ -0,0 +1,40 @@
+# Development
+
+Install the package in editable mode:
+
+```sh
+$ git clone git@github.com:koxudaxi/datamodel-code-generator.git
+$ pip install -e datamodel-code-generator
+```
+
+# Contribute
+We are waiting for your contributions to `datamodel-code-generator`.
+
+## How to contribute
+
+```bash
+## 1. Clone your fork repository
+$ git clone git@github.com:<your username>/datamodel-code-generator.git
+$ cd datamodel-code-generator
+
+## 2. Create `venv` with python3.7 (also you should do with python3.6)
+$ python3.7 -m venv venv37
+$ source venv37/bin/activate  
+
+## 3. Install dependencies
+$ python3 -m pip install ".[all]" 
+
+## 4. Create new branch and rewrite code.
+$ git checkout -b new-branch
+
+## 5. Run unittest (you should pass all test and coverage should be 100%)
+$ ./scripts/test.sh
+
+## 6. Format code
+$ ./scripts/format.sh
+
+## 7. Check lint (mypy)
+$ ./scripts/lint.sh
+
+## 8. Commit and Push...
+```
--- a/docs/formatting.md
+++ b/docs/formatting.md
@@ -0,0 +1,23 @@
+# Formatting
+
+Code generated by `datamodel-codegen` will be passed through `isort` and
+`black` to produce consistent, well-formatted results. Settings for these tools
+can be specified in `pyproject.toml` (located in the output directory, or in
+some parent of the output directory).
+
+Example `pyproject.toml`:
+```toml
+[tool.black]
+skip-string-normalization = true
+line-length = 100
+
+[tool.isort]
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+line_length = 100
+known_first_party = "kelvin"
+```
+
+See the [Black Project](https://black.readthedocs.io/en/stable/pyproject_toml.html) for more information.
--- a/docs/index.md
+++ b/docs/index.md
@@ -0,0 +1,275 @@
+# datamodel-code-generator
+
+This code generator creates pydantic model from an openapi file and others.
+
+[![Build Status](https://travis-ci.org/koxudaxi/datamodel-code-generator.svg?branch=master)](https://travis-ci.org/koxudaxi/datamodel-code-generator)
+[![PyPI version](https://badge.fury.io/py/datamodel-code-generator.svg)](https://pypi.python.org/pypi/datamodel-code-generator)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/datamodel-code-generator)](https://pypi.python.org/pypi/datamodel-code-generator)
+[![codecov](https://codecov.io/gh/koxudaxi/datamodel-code-generator/branch/master/graph/badge.svg)](https://codecov.io/gh/koxudaxi/datamodel-code-generator)
+![license](https://img.shields.io/github/license/koxudaxi/datamodel-code-generator.svg)
+
+
+## Supported file formats
+- OpenAPI 3 (yaml/json)
+- JsonSchema
+- Json/Yaml Data (it will be converted to JsonSchema)
+
+## Installation
+
+To install `datamodel-code-generator`:
+```sh
+$ pip install datamodel-code-generator
+```
+
+## Usage
+
+The `datamodel-codegen` command:
+```
+usage: datamodel-codegen [-h] [--input INPUT] [--output OUTPUT]
+                         [--base-class BASE_CLASS]
+                         [--custom-template-dir CUSTOM_TEMPLATE_DIR]
+                         [--extra-template-data EXTRA_TEMPLATE_DATA]
+                         [--target-python-version {3.6,3.7}] [--debug]
+                         [--validation Enable validation (Only OpenAPI)]
+                         [--version]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --input INPUT         Input file (default: stdin)
+  --input-file-type {auto,openapi,jsonscehma,json,yaml}
+  --output OUTPUT       Output file (default: stdout)
+  --base-class BASE_CLASS
+                        Base Class (default: pydantic.BaseModel)
+  --custom-template-dir CUSTOM_TEMPLATE_DIR
+                        Custom Template Directory
+  --extra-template-data EXTRA_TEMPLATE_DATA
+                        Extra Template Data
+  --target-python-version {3.6,3.7}
+                        target python version (default: 3.7)
+  --validation          Enable validation (Only OpenAPI)
+  --debug               show debug message
+  --version             show version
+```
+
+## Example
+### OpenAPI
+```sh
+$ datamodel-codegen --input api.yaml --output model.py
+```
+
+<details>
+<summary>api.yaml</summary>
+<pre>
+<code>
+```yaml
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+            x-next:
+              description: A link to the next page of responses
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+                x-amazon-apigateway-integration:
+                  uri:
+                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+                  passthroughBehavior: when_no_templates
+                  httpMethod: POST
+                  type: aws_proxy
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      responses:
+        '201':
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+                x-amazon-apigateway-integration:
+                  uri:
+                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+                  passthroughBehavior: when_no_templates
+                  httpMethod: POST
+                  type: aws_proxy
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    x-amazon-apigateway-integration:
+      uri:
+        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+      passthroughBehavior: when_no_templates
+      httpMethod: POST
+      type: aws_proxy
+components:
+  schemas:
+    Pet:
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+    Error:
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string
+    apis:
+      type: array
+      items:
+        type: object
+        properties:
+          apiKey:
+            type: string
+            description: To be used as a dataset parameter value
+          apiVersionNumber:
+            type: string
+            description: To be used as a version parameter value
+          apiUrl:
+            type: string
+            format: uri
+            description: "The URL describing the dataset's fields"
+          apiDocumentationUrl:
+            type: string
+            format: uri
+            description: A URL to the API console for each API
+```
+</code>
+</pre>
+</details>
+
+`model.py`:
+```python
+# generated by datamodel-codegen:
+#   filename:  api.yaml
+#   timestamp: 2020-03-09T15:51:49+00:00
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import AnyUrl, BaseModel, Field
+
+
+class Pet(BaseModel):
+    id: int
+    name: str
+    tag: Optional[str] = None
+
+
+class Pets(BaseModel):
+    __root__: List[Pet]
+
+
+class Error(BaseModel):
+    code: int
+    message: str
+
+
+class api(BaseModel):
+    apiKey: Optional[str] = Field(
+        None, description='To be used as a dataset parameter value'
+    )
+    apiVersionNumber: Optional[str] = Field(
+        None, description='To be used as a version parameter value'
+    )
+    apiUrl: Optional[AnyUrl] = Field(
+        None, description="The URL describing the dataset's fields"
+    )
+    apiDocumentationUrl: Optional[AnyUrl] = Field(
+        None, description='A URL to the API console for each API'
+    )
+
+
+class apis(BaseModel):
+    __root__: List[api]
+```
+
+## PyPi 
+
+[https://pypi.org/project/datamodel-code-generator](https://pypi.org/project/datamodel-code-generator)
+
+## Source Code
+
+[https://github.com/koxudaxi/datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator)
+
+## License
+
+datamodel-code-generator is released under the MIT License. http://www.opensource.org/licenses/mit-license
+
+## This project is an experimental phase.
--- a/docs/jsondata.md
+++ b/docs/jsondata.md
@@ -0,0 +1,57 @@
+# Generate from JsonData
+
+The codegen generate pydantic models from JsonData
+
+## Example
+
+```bash
+$ datamodel-codegen  --input pets.json --input-file-type json --output model.py
+```
+
+`pets.json`:
+```json
+{
+  "pets": [
+    {
+      "name": "dog",
+      "age": 2
+    },
+    {
+      "name": "cat",
+      "age": 1
+    },
+    {
+      "name": "snake",
+      "age": 3,
+      "nickname": "python"
+    }
+  ],
+  "status": 200
+}
+```
+
+
+`model.py`:
+```python
+# generated by datamodel-codegen:
+#   filename:  pets.json
+#   timestamp: 2020-04-27T16:08:21+00:00
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class Pet(BaseModel):
+    name: str
+    age: int
+    nickname: Optional[str] = None
+
+
+class Model(BaseModel):
+    pets: List[Pet]
+    status: int
+
+```
--- a/docs/jsonschema.md
+++ b/docs/jsonschema.md
@@ -0,0 +1,64 @@
+# Generate from JsonSchema
+
+The codegen generate pydantic models from JsonSchema
+
+## Example
+
+```bash
+$ datamodel-codegen  --input person.json --input-file-type jsonshema --output model.py
+```
+
+`person.json`:
+```json
+{
+  "$id": "https://example.com/person.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Person",
+  "type": "object",
+  "properties": {
+    "firstName": {
+      "type": "string",
+      "description": "The person's first name."
+    },
+    "lastName": {
+      "type": "string",
+      "description": "The person's last name."
+    },
+    "age": {
+      "description": "Age in years which must be equal to or greater than zero.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "friends": {
+      "type": "array"
+    },
+    "comment": {
+      "type": "null"
+    }
+  }
+}
+```
+
+
+`model.py`:
+```python
+# generated by datamodel-codegen:
+#   filename:  person.json
+#   timestamp: 2020-04-27T16:12:27+00:00
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field, conint
+
+
+class Person(BaseModel):
+    firstName: Optional[str] = Field(None, description="The person's first name.")
+    lastName: Optional[str] = Field(None, description="The person's last name.")
+    age: Optional[conint(ge=0.0)] = Field(
+        None, description='Age in years which must be equal to or greater than zero.'
+    )
+    friends: Optional[List] = None
+    comment: Optional[Any] = None
+```
--- a/docs/openapi.md
+++ b/docs/openapi.md
@@ -0,0 +1,212 @@
+# Generate from OpenAPI
+
+The codegen generate pydantic models from OpenAPI
+
+## Example
+
+```bash
+$ datamodel-codegen --input api.yaml --input-file-type openapi --output model.py
+```
+
+<details>
+<summary>api.yaml</summary>
+<pre>
+<code>
+```yaml
+openapi: "3.0.0"
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+servers:
+  - url: http://petstore.swagger.io/v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      parameters:
+        - name: limit
+          in: query
+          description: How many items to return at one time (max 100)
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: A paged array of pets
+          headers:
+            x-next:
+              description: A link to the next page of responses
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+                x-amazon-apigateway-integration:
+                  uri:
+                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+                  passthroughBehavior: when_no_templates
+                  httpMethod: POST
+                  type: aws_proxy
+    post:
+      summary: Create a pet
+      operationId: createPets
+      tags:
+        - pets
+      responses:
+        '201':
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+                x-amazon-apigateway-integration:
+                  uri:
+                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+                  passthroughBehavior: when_no_templates
+                  httpMethod: POST
+                  type: aws_proxy
+  /pets/{petId}:
+    get:
+      summary: Info for a specific pet
+      operationId: showPetById
+      tags:
+        - pets
+      parameters:
+        - name: petId
+          in: path
+          required: true
+          description: The id of the pet to retrieve
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    x-amazon-apigateway-integration:
+      uri:
+        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
+      passthroughBehavior: when_no_templates
+      httpMethod: POST
+      type: aws_proxy
+components:
+  schemas:
+    Pet:
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      items:
+        $ref: "#/components/schemas/Pet"
+    Error:
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string
+    apis:
+      type: array
+      items:
+        type: object
+        properties:
+          apiKey:
+            type: string
+            description: To be used as a dataset parameter value
+          apiVersionNumber:
+            type: string
+            description: To be used as a version parameter value
+          apiUrl:
+            type: string
+            format: uri
+            description: "The URL describing the dataset's fields"
+          apiDocumentationUrl:
+            type: string
+            format: uri
+            description: A URL to the API console for each API
+```
+</code>
+</pre>
+</details>
+
+`model.py`:
+```python
+# generated by datamodel-codegen:
+#   filename:  api.yaml
+#   timestamp: 2020-03-09T15:51:49+00:00
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import AnyUrl, BaseModel, Field
+
+
+class Pet(BaseModel):
+    id: int
+    name: str
+    tag: Optional[str] = None
+
+
+class Pets(BaseModel):
+    __root__: List[Pet]
+
+
+class Error(BaseModel):
+    code: int
+    message: str
+
+
+class api(BaseModel):
+    apiKey: Optional[str] = Field(
+        None, description='To be used as a dataset parameter value'
+    )
+    apiVersionNumber: Optional[str] = Field(
+        None, description='To be used as a version parameter value'
+    )
+    apiUrl: Optional[AnyUrl] = Field(
+        None, description="The URL describing the dataset's fields"
+    )
+    apiDocumentationUrl: Optional[AnyUrl] = Field(
+        None, description='A URL to the API console for each API'
+    )
+
+
+class apis(BaseModel):
+    __root__: List[api]
+```
--- a/docs/support-data-types.md
+++ b/docs/support-data-types.md
@@ -0,0 +1,27 @@
+# Implemented list
+
+This codegen supports major data types to OpenAPI/JsonSchema
+
+## OpenAPI 3 and JsonSchema
+### DataType
+- string (include patter/minLength/maxLenght)
+- number (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
+- integer (include maximum/exclusiveMaximum/minimum/exclusiveMinimum/multipleOf/le/ge)
+- boolean
+- array
+- object
+
+#### String Format 
+- date
+- datetime
+- password
+- email
+- uuid (uuid1/uuid2/uuid3/uuid4/uuid5)
+- ipv4
+- ipv6
+
+### Other schema
+- enum
+- allOf (as Multiple inheritance)
+- anyOf (as Union)
+- $ref (exclude URL Reference)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,5 +1,5 @@
 site_name: datamodel-code-generator
-site_description: This generator creates pydantic mode from an openapi file.
+site_description: This code generator creates pydantic model from an openapi file and others.

 theme:
    name: 'material'
@@ -9,6 +9,7 @@ theme:

 markdown_extensions:
  - codehilite
+  - admonition

 repo_name: koxudaxi/datamodel-code-generator
 repo_url: https://github.com/koxudaxi/datamodel-code-generator
@@ -18,4 +19,14 @@ google_analytics:
    - 'auto'

 nav:
-    - datamodel-code-generator: 'index.md'
+    - Overview: index.md
+    - Support data types: support-data-types.md
+    - Usage:
+      - Generate from OpenAPI: openapi.md
+      - Generate from JsonSchema: jsonschema.md
+      - Generate from JsonData: jsondata.md
+      - Formatting: formatting.md
+    - Development-Contributing: development-contributing.md
+
+plugins:
+  - search