Better example based on actual api usage

Author: phillipdupuis

README.md

@@ -18,65 +18,77 @@ $ pip install pydantic-to-typescript
 |‑‑json2ts‑cmd|optional, the command used to invoke json2ts. The default is 'json2ts'. Specify this if you have it installed in a strange location and need to provide the exact path (ex: /myproject/node_modules/bin/json2ts)|
 ---
 ### Usage
-pydantic2ts/examples/pydantic_models.py:
+Define your pydantic models (ex: /backend/api.py):
 ```python
-from pydantic import BaseModel, Extra
-from enum import Enum
-from typing import List, Dict
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import List, Optional
 
+api = FastAPI()
 
-class NoExtraProps:
-    extra = Extra.forbid
+class LoginCredentials(BaseModel):
+    username: str
+    password: str
 
+class Profile(BaseModel):
+    username: str
+    age: Optional[int]
+    hobbies: List[str]
 
-class Sport(str, Enum):
-    football = 'football'
-    basketball = 'basketball'
+class LoginResponseData(BaseModel):
+    token: str
+    profile: Profile
 
-
-class Athlete(BaseModel):
-    name: str
-    age: int
-    sports: List[Sport]
-    Config = NoExtraProps
-
-
-class Team(BaseModel):
-    name: str
-    sport: Sport
-    athletes: List[Athlete]
-    Config = NoExtraProps
-
-
-class League(BaseModel):
-    cities: Dict[str, Team]
-    Config = NoExtraProps
+@api.post('/login/', response_model=LoginResponseData)
+def login(body: LoginCredentials):
+    profile = Profile(**body.dict(), age=72, hobbies=['cats'])
+    return LoginResponseData(token='very-secure', profile=profile)
 ```
-Command-line:
+Execute the command for converting these models into typescript definitions:
 ```bash
-$ pydantic2ts --module pydantic2ts.examples.pydantic_models --output output.ts
-```
-output.ts:
+$ pydantic2ts --module backend.api --output ./frontend/apiTypes.ts
 ```
+The models are now defined in typescript...
+```ts
 /* tslint:disable */
 /**
 /* This file was automatically generated from pydantic models by running pydantic2ts.
 /* Do not modify it by hand - just update the pydantic models and then re-run the script
 */
 
-export interface Athlete {
-  name: string;
-  age: number;
-  sports: ("football" | "basketball")[];
+export interface LoginCredentials {
+  username: string;
+  password: string;
+}
+export interface LoginResponseData {
+  token: string;
+  profile: Profile;
 }
-export interface League {
-  cities: {
-    [k: string]: Team;
-  };
+export interface Profile {
+  username: string;
+  age?: number;
+  hobbies: string[];
 }
-export interface Team {
-  name: string;
-  sport: "football" | "basketball";
-  athletes: Athlete[];
+```
+...and can be used in your typescript code with complete confidence.
+```ts
+import { LoginCredentials, LoginResponseData } from './apiTypes.ts';
+
+async function login(
+  credentials: LoginCredentials,
+  resolve: (data: LoginResponseData) => void,
+  reject: (error: string) => void,
+) {
+  try {
+    const response: Response = await fetch('/login/', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify(credentials),
+    });
+    const data: LoginResponseData = await response.json();
+    resolve(data);
+  } catch (error) {
+    reject(error.message);
+  }
 }
 ```

pydantic2ts/cli/script.py

@@ -3,21 +3,28 @@
 import importlib
 import os
 import shutil
-from pydantic import BaseModel, create_model
+from pydantic import BaseModel, Extra, create_model
 from tempfile import mkdtemp
 from typing import Type, Dict, Any, List
 from types import ModuleType
 
 
-def remove_property_titles(schema: Dict[str, Any], model: Type[BaseModel]) -> None:
+def clean_schema(schema: Dict[str, Any], model: Type[BaseModel]) -> None:
     """
-    Monkey-patched method for removing titles from JSON schema properties.
-    If we don't do this, each property will have its own interface in the
-    resulting typescript file (which is a LOT of unnecessary noise).
+    Monkey-patched method for cleaning up resulting JSON schemas by:
+
+    1) Removing titles from JSON schema properties.
+       If we don't do this, each property will have its own interface in the
+       resulting typescript file (which is a LOT of unnecessary noise).
+    2) Setting 'additionalProperties' to False UNLESS Config.extra is explicitly
+       set to "allow". This keeps the typescript interfaces clean (ie useful).
     """
     for prop in schema.get('properties', {}).values():
         prop.pop('title', None)
 
+    if model.Config.extra != Extra.allow:
+        schema['additionalProperties'] = False
+
 
 def not_private(obj) -> bool:
     """Return true if an object does not seem to be private"""
@@ -95,10 +102,10 @@ def main(
     models = extract_pydantic_models(importlib.import_module(module))
 
     for m in models:
-        m.Config.schema_extra = staticmethod(remove_property_titles)
+        m.Config.schema_extra = staticmethod(clean_schema)
 
     master_model = create_model('_Master_', **{m.__name__: (m, ...) for m in models})
-    master_model.Config.schema_extra = staticmethod(remove_property_titles)
+    master_model.Config.schema_extra = staticmethod(clean_schema)
 
     schema_dir = mkdtemp()
     schema_file_path = os.path.join(schema_dir, 'schema.json')

pydantic2ts/examples/api.py

@@ -0,0 +1,27 @@
+from fastapi import FastAPI
+from pydantic import BaseModel
+from typing import List, Optional
+
+api = FastAPI()
+
+
+class LoginCredentials(BaseModel):
+    username: str
+    password: str
+
+
+class Profile(BaseModel):
+    username: str
+    age: Optional[int]
+    hobbies: List[str]
+
+
+class LoginResponseData(BaseModel):
+    token: str
+    profile: Profile
+
+
+@api.post('/login/', response_model=LoginResponseData)
+def login(body: LoginCredentials):
+    profile = Profile(**body.dict(), age=72, hobbies=['cats'])
+    return LoginResponseData(token='very-secure', profile=profile)

pydantic2ts/examples/apiTypes.ts

@@ -0,0 +1,19 @@
+/* tslint:disable */
+/**
+/* This file was automatically generated from pydantic models by running pydantic2ts.
+/* Do not modify it by hand - just update the pydantic models and then re-run the script
+*/
+
+export interface LoginCredentials {
+  username: string;
+  password: string;
+}
+export interface LoginResponseData {
+  token: string;
+  profile: Profile;
+}
+export interface Profile {
+  username: string;
+  age?: number;
+  hobbies: string[];
+}

pydantic2ts/examples/convert.sh

@@ -1,3 +1,2 @@
 #!/bin/bash
-
-pydantic2ts --module pydantic2ts.examples.pydantic_models --output output.ts
+pydantic2ts --module pydantic2ts.examples.api --output apiTypes.ts

pydantic2ts/examples/output.ts

@@ -20,7 +20,7 @@ def readme():
 
 setup(
     name='pydantic-to-typescript',
-    version='1.0.4',
+    version='1.0.5',
     description='Convert pydantic models to typescript interfaces',
     license='MIT',
     long_description=readme(),