|
1 | | -# neuma-api-dart README |
2 | | - |
3 | | -This is the README for your extension "neuma-api-dart". After writing up a brief description, we recommend including the following sections. |
4 | | - |
5 | | -## Features |
6 | | - |
7 | | -Describe specific features of your extension including screenshots of your extension in action. Image paths are relative to this README file. |
8 | | - |
9 | | -For example if there is an image subfolder under your extension project workspace: |
10 | | - |
11 | | -\!\[feature X\]\(images/feature-x.png\) |
12 | | - |
13 | | -> Tip: Many popular extensions utilize animations. This is an excellent way to show off your extension! We recommend short, focused animations that are easy to follow. |
14 | | -
|
15 | | -## Requirements |
16 | | - |
17 | | -If you have any requirements or dependencies, add a section describing those and how to install and configure them. |
18 | | - |
19 | | -## Extension Settings |
20 | | - |
21 | | -Include if your extension adds any VS Code settings through the `contributes.configuration` extension point. |
22 | | - |
23 | | -For example: |
24 | | - |
25 | | -This extension contributes the following settings: |
26 | | - |
27 | | -* `myExtension.enable`: Enable/disable this extension. |
28 | | -* `myExtension.thing`: Set to `blah` to do something. |
29 | | - |
30 | | -## Known Issues |
31 | | - |
32 | | -Calling out known issues can help limit users opening duplicate issues against your extension. |
33 | | - |
34 | | -## Release Notes |
35 | | - |
36 | | -Users appreciate release notes as you update your extension. |
37 | | - |
38 | | -### 1.0.0 |
39 | | - |
40 | | -Initial release of ... |
41 | | - |
42 | | -### 1.0.1 |
43 | | - |
44 | | -Fixed issue #. |
45 | | - |
46 | | -### 1.1.0 |
47 | | - |
48 | | -Added features X, Y, and Z. |
49 | | - |
50 | | ---- |
51 | | - |
52 | | -## Following extension guidelines |
53 | | - |
54 | | -Ensure that you've read through the extensions guidelines and follow the best practices for creating your extension. |
55 | | - |
56 | | -* [Extension Guidelines](https://code.visualstudio.com/api/references/extension-guidelines) |
57 | | - |
58 | | -## Working with Markdown |
59 | | - |
60 | | -You can author your README using Visual Studio Code. Here are some useful editor keyboard shortcuts: |
61 | | - |
62 | | -* Split the editor (`Cmd+\` on macOS or `Ctrl+\` on Windows and Linux). |
63 | | -* Toggle preview (`Shift+Cmd+V` on macOS or `Shift+Ctrl+V` on Windows and Linux). |
64 | | -* Press `Ctrl+Space` (Windows, Linux, macOS) to see a list of Markdown snippets. |
65 | | - |
66 | | -## For more information |
67 | | - |
68 | | -* [Visual Studio Code's Markdown Support](http://code.visualstudio.com/docs/languages/markdown) |
69 | | -* [Markdown Syntax Reference](https://help.github.com/articles/markdown-basics/) |
70 | | - |
71 | | -**Enjoy!** |
| 1 | + |
| 2 | + |
| 3 | +## ✨ What is Neuma API Dart? |
| 4 | + |
| 5 | +**Neuma API Dart** is a powerful VS Code extension designed to simplify your Flutter backend integration process by automatically creating folders and Dart files for you. |
| 6 | + |
| 7 | +This extension is suitable for any Dart project. Although it is made to pair seamlessly with [Neuma Base Flutter](https://github.com/abelherl/neuma-base-flutter), this tool allows you to **generate Dart models instantly from JSON**, complete with support for: |
| 8 | + |
| 9 | +* `fromJson` and `toJson` for request and response |
| 10 | +* Deeply nested classes |
| 11 | +* CamelCase field conversion |
| 12 | +* Freezed & Equatable (optional) |
| 13 | +* ```copyWith()``` / ```toString()``` generation |
| 14 | + |
| 15 | +Whether you’re building requests or parsing responses, **Neuma API Dart** keeps your workflow rapid, consistent, and efficient. |
| 16 | + |
| 17 | +## ⚙️ Features |
| 18 | + |
| 19 | +* 🔧 Generate Dart models with one command |
| 20 | +* 🧠 Smart type inference with nested class generation |
| 21 | +* 📦 Support for arrays and objects of any depth |
| 22 | +* 🎯 Choose between **Request** or **Response** generation |
| 23 | +* 🧩 Optional: Freezed, JsonSerializable, Equatable, CopyWith |
| 24 | + |
| 25 | +## 🚀 Getting Started |
| 26 | +### 1. Install the Extension |
| 27 | +From VS Code: |
| 28 | + |
| 29 | +* Search for `Neuma API Dart` in the extensions marketplace and install |
| 30 | + |
| 31 | +Or via CLI: |
| 32 | + |
| 33 | +```bash |
| 34 | +code --install-extension neuma-api-dart-x.x.x.vsix |
| 35 | +``` |
| 36 | + |
| 37 | +### 2. Use the Command |
| 38 | +Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), then run: |
| 39 | + |
| 40 | +``` |
| 41 | +Neuma API: Convert JSON to Dart Model |
| 42 | +``` |
| 43 | + |
| 44 | +You will be prompted to: |
| 45 | + |
| 46 | +* Paste your JSON |
| 47 | +* Choose **Request** or **Response** |
| 48 | +* Enter a class name |
| 49 | + |
| 50 | +The Dart model is automatically generated and copied to your clipboard! 🥳✨ |
| 51 | + |
| 52 | +## 📄 Example: Input & Output |
| 53 | + |
| 54 | +### 🔁 Response Input |
| 55 | +```json |
| 56 | +{ |
| 57 | + "id": 42, |
| 58 | + "title": "Sample Post", |
| 59 | + "author": { |
| 60 | + "id": 1, |
| 61 | + "name": "Jane Doe" |
| 62 | + }, |
| 63 | + "tags": ["flutter", "dart"] |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +### ✅ Generated Dart (Response) |
| 68 | +```dart |
| 69 | +class SampleResponse { |
| 70 | + final int id; |
| 71 | + final String title; |
| 72 | + final SampleAuthorResponse author; |
| 73 | + final List<String> tags; |
| 74 | +
|
| 75 | + const SampleResponse({ |
| 76 | + required this.id, |
| 77 | + required this.title, |
| 78 | + required this.author, |
| 79 | + required this.tags, |
| 80 | + }); |
| 81 | +
|
| 82 | + factory SampleResponse.fromJson(Map<String, dynamic> json) { |
| 83 | + return SampleResponse( |
| 84 | + id: json['id'], |
| 85 | + title: json['title'], |
| 86 | + author: SampleAuthorResponse.fromJson(json['author']), |
| 87 | + tags: List<String>.from(json['tags']), |
| 88 | + ); |
| 89 | + } |
| 90 | +} |
| 91 | +
|
| 92 | +class SampleAuthorResponse { |
| 93 | + final int id; |
| 94 | + final String name; |
| 95 | +
|
| 96 | + const SampleAuthorResponse({ |
| 97 | + required this.id, |
| 98 | + required this.name, |
| 99 | + }); |
| 100 | +
|
| 101 | + factory SampleAuthorResponse.fromJson(Map<String, dynamic> json) { |
| 102 | + return SampleAuthorResponse( |
| 103 | + id: json['id'], |
| 104 | + name: json['name'], |
| 105 | + ); |
| 106 | + } |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +### 📤 Request Input |
| 111 | +```json |
| 112 | +{ |
| 113 | + "title": "Create New Post", |
| 114 | + "body": "This is the body of the new post", |
| 115 | + "tags": ["flutter", "api"] |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +### ✅ Generated Dart (Request) |
| 120 | +```dart |
| 121 | +class CreatePostRequest { |
| 122 | + final String title; |
| 123 | + final String body; |
| 124 | + final List<String> tags; |
| 125 | +
|
| 126 | + const CreatePostRequest({ |
| 127 | + required this.title, |
| 128 | + required this.body, |
| 129 | + required this.tags, |
| 130 | + }); |
| 131 | +
|
| 132 | + Map<String, dynamic> toJson() { |
| 133 | + return { |
| 134 | + 'title': title, |
| 135 | + 'body': body, |
| 136 | + 'tags': tags, |
| 137 | + }; |
| 138 | + } |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +### 📁 Folder Structure |
| 143 | + |
| 144 | +You can customize the generation folder if you need to. |
| 145 | + |
| 146 | +``` |
| 147 | +📁 lib/ |
| 148 | +├── 📁 models/ |
| 149 | +│ ├── 📁 create_post/ |
| 150 | +│ │ ├── create_post_request.dart |
| 151 | +│ │ ├── create_post_response.dart |
| 152 | +│ │── 📁 sample/ |
| 153 | +│ │ ├── sample_request.dart |
| 154 | +│ │ ├── sample_response.dart |
| 155 | +``` |
| 156 | + |
| 157 | +## 🛠️ Future Plans |
| 158 | +* ⏳ Convert from Postman or Swagger JSON collection |
| 159 | + |
| 160 | + |
| 161 | +## 📄 License |
| 162 | +Licensed under the [MIT License](./LICENSE) |
0 commit comments