Skip to content

Commit 6afee91

Browse files
gibahjoegibahjoe
committed
docs: Update README files for clarity, deprecate skipIfSpecIsUnchanged, and enhance usage instructions
1 parent 8071284 commit 6afee91

File tree

3 files changed

+449
-257
lines changed

3 files changed

+449
-257
lines changed

‎README.md

Lines changed: 141 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,131 +1,151 @@
1-
![pub package](https://img.shields.io/pub/v/openapi_generator.svg) ![Pub Likes](https://img.shields.io/pub/likes/openapi_generator?) ![Pub Points](https://img.shields.io/pub/points/openapi_generator) ![Pub Popularity](https://img.shields.io/pub/popularity/openapi_generator) ![GitHub Repo stars](https://img.shields.io/github/stars/gibahjoe/openapi-generator-dart)
1+
# openapi-generator-dart
2+
3+
[![pub package](https://img.shields.io/pub/v/openapi_generator.svg)](https://pub.dev/packages/openapi_generator)
4+
[![Pub Likes](https://img.shields.io/pub/likes/openapi_generator?)](https://pub.dev/packages/openapi_generator)
5+
[![Pub Points](https://img.shields.io/pub/points/openapi_generator)](https://pub.dev/packages/openapi_generator)
6+
[![Pub Popularity](https://img.shields.io/pub/popularity/openapi_generator)](https://pub.dev/packages/openapi_generator)
7+
[![GitHub Repo stars](https://img.shields.io/github/stars/gibahjoe/openapi-generator-dart)](https://github.com/gibahjoe/openapi-generator-dart)
28
[![codecov](https://codecov.io/gh/gibahjoe/openapi-generator-dart/graph/badge.svg?token=MF8SDQJMGP)](https://codecov.io/gh/gibahjoe/openapi-generator-dart)
39

4-
### Like this library? Give us a star or a like.
10+
> **Like this library?** Give us a star or a like!
511
6-
This codebase houses the dart/flutter implementations of the openapi client sdk code generation libraries.
12+
---
713

8-
## TOC
14+
## ⚠️ Java Requirement
915

10-
- [Introduction](#introduction)
11-
- [Usage](#usage)
12-
- [NextGen](#next-generation)
13-
- [Features & Bugs](#features-and-bugs)
16+
> **Java is required to use this library.**
17+
> The OpenAPI Generator CLI is a Java application.
18+
> Please ensure you have Java (version 8 or higher) installed and available in your system PATH.
19+
> You can check your Java installation with:
20+
>
21+
> ```sh
22+
> java -version
23+
> ```
24+
>
25+
> If you do not have Java installed, download it from [Adoptium](https://adoptium.net/) or [Oracle](https://www.oracle.com/java/technologies/downloads/).
1426
15-
## Introduction
27+
---
1628
17-
With this project, you can generate client libraries from your openapi specification right in your
18-
flutter/dart projects (see example). This library was inspired by the npm
19-
counterpart [Openapi Generator Cli](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)
29+
## ⚠️ Deprecation & Breaking Change Notice
2030
21-
[license](https://github.com/gibahjoe/openapi-generator-dart/blob/master/openapi-generator-annotations/LICENSE).
31+
### `skipIfSpecIsUnchanged` is Deprecated
2232
23-
This repo contains the following dart libraries
33+
- The `skipIfSpecIsUnchanged` option is now **deprecated** and will be removed in the next major release.
34+
- **Local OpenAPI specs** are now automatically watched for changes.
35+
- If your spec file is in the `lib/` folder, this works out of the box.
36+
- If your spec file is outside `lib/`, you must update or add a `build.yaml` to include your spec file as a source.
37+
Example:
38+
```yaml
39+
targets:
40+
$default:
41+
sources:
42+
- $package$
43+
- lib/**
44+
- openapi.yaml # or your spec file path
45+
```
46+
- **Remote specs:**
47+
Use the `forceAlwaysRun` (defaults to false) option to ensure the generator always runs.
48+
- This option is ignored for local specs.
49+
- When enabled, it modifies the annotated file to force regeneration. This might cause issues such as merge conflicts
2450
25-
| Library | Description | latest version |
26-
|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
27-
| openapi-generator | Dev dependency for generating openapi client sdk via dart source gen [see here for usage](https://pub.dev/packages/openapi_generator) | [![pub package](https://img.shields.io/pub/v/openapi_generator.svg)](https://pub.dev/packages/openapi_generator) |
28-
| openapi-generator-annotations | Annotations for annotating dart class with instructions for generating openapi client sdk [see here for usage](https://pub.dev/packages/openapi_generator_annotations) | [![pub package](https://img.shields.io/pub/v/openapi_generator_annotations.svg)](https://pub.dev/packages/openapi_generator) |
29-
| openapi-generator-cli | CLI only generator. [see here for usage](https://pub.dev/packages/openapi_generator_cli) | [![pub package](https://img.shields.io/pub/v/openapi_generator_cli.svg)](https://pub.dev/packages/openapi_generator_cli) |
51+
---
3052
31-
## Usage
53+
## Overview
3254
33-
Include [openapi-generator-annotations](https://pub.dev/packages/openapi_generator_annotations) as a dependency in the
34-
dependencies section of your pubspec.yaml file :
55+
This repository provides Dart/Flutter libraries for generating OpenAPI client SDKs directly from your OpenAPI specification. Inspired by [Openapi Generator Cli (npm)](https://www.npmjs.com/package/@openapitools/openapi-generator-cli), it enables seamless integration into Dart and Flutter projects.
3556
36-
```yaml
37-
dependencies:
38-
openapi_generator_annotations: ^[latest-version]
39-
```
57+
### Libraries
4058
41-
For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for
42-
production builds
59+
| Library | Description | Latest Version |
60+
|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
61+
| openapi-generator | Dev dependency for generating OpenAPI client SDK via Dart source gen ([usage](https://pub.dev/packages/openapi_generator)) | [![pub package](https://img.shields.io/pub/v/openapi_generator.svg)](https://pub.dev/packages/openapi_generator) |
62+
| openapi-generator-annotations | Annotations for configuring OpenAPI client SDK generation ([usage](https://pub.dev/packages/openapi_generator_annotations)) | [![pub package](https://img.shields.io/pub/v/openapi_generator_annotations.svg)](https://pub.dev/packages/openapi_generator_annotations) |
63+
| openapi-generator-cli | CLI wrapper for OpenAPI code generation ([usage](https://pub.dev/packages/openapi_generator_cli)) | [![pub package](https://img.shields.io/pub/v/openapi_generator_cli.svg)](https://pub.dev/packages/openapi_generator_cli) |
4364
44-
```yaml
45-
dependencies:
46-
openapi_generator_annotations:
47-
git:
48-
url: https://github.com/gibahjoe/openapi-generator-dart.git
49-
ref: beta
50-
path: openapi-generator-annotations
51-
```
65+
---
66+
67+
## Quick Start
68+
69+
### 1. Add Dependencies
5270
53-
Add [openapi-generator](https://pub.dev/packages/openapi_generator) in the dev dependencies section of your pubspec.yaml
54-
file:
71+
Add the annotations package to your `pubspec.yaml`:
5572
5673
```yaml
57-
dev_dependencies:
58-
openapi_generator: ^[latest version]
74+
dependencies:
75+
openapi_generator_annotations: ^<latest-version>
5976
```
6077
61-
For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for
62-
production builds
78+
Add the generator as a dev dependency:
6379
6480
```yaml
6581
dev_dependencies:
66-
openapi_generator:
67-
git:
68-
url: https://github.com/gibahjoe/openapi-generator-dart.git
69-
ref: beta
70-
path: openapi-generator
82+
openapi_generator: ^<latest-version>
7183
```
7284
73-
Annotate a dart class with @Openapi() annotation
85+
> **Beta Features:**
86+
> For beta features, use the `beta` branch:
87+
>
88+
> ```yaml
89+
> dependencies:
90+
> openapi_generator_annotations:
91+
> git:
92+
> url: https://github.com/gibahjoe/openapi-generator-dart.git
93+
> ref: beta
94+
> path: openapi-generator-annotations
95+
>
96+
> dev_dependencies:
97+
> openapi_generator:
98+
> git:
99+
> url: https://github.com/gibahjoe/openapi-generator-dart.git
100+
> ref: beta
101+
> path: openapi-generator
102+
> ```
103+
104+
### 2. Annotate Your Dart Class
105+
106+
Annotate a Dart class with `@Openapi()` to configure code generation:
74107
75108
```dart
109+
import 'package:openapi_generator_annotations/openapi_generator_annotations.dart';
110+
76111
@Openapi(
77-
additionalProperties:
78-
DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep..'),
79-
inputSpec:
80-
RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
112+
additionalProperties: DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny Depp'),
113+
inputSpec: RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
81114
typeMappings: {'Pet': 'ExamplePet'},
82115
generatorName: Generator.dio,
83116
runSourceGenOnOutput: true,
84117
outputDirectory: 'api/petstore_api',
85118
)
119+
class Example {}
86120
```
87121
88-
Run
89-
90-
```shell
91-
dart run build_runner build --delete-conflicting-outputs
92-
```
122+
### 3. Generate the SDK
93123

94-
or
124+
Run the build command:
95125

96-
```shell
126+
```sh
127+
dart run build_runner build --delete-conflicting-outputs
128+
# or, for Flutter projects:
97129
flutter pub run build_runner build --delete-conflicting-outputs
98130
```
99131

100-
to generate open api client sdk from spec file specified in annotation.
101-
The api sdk will be generated in the folder specified in the annotation. See examples for more details
102-
103-
## Next Generation
132+
The generated SDK will appear in the specified output directory.
104133

105-
As of version 5.0 of this library, there is some new functionality slated to be added to the generator. This version
106-
will have the ability to:
134+
---
107135

108-
- cache changes in the OAS spec
109-
- Rerun when there ares difference in the cached copy and current copy
110-
- Pull from a remote source and cache that.
111-
- **Note**: This means that your cache could be potentially stale. But in that case this flow will still pull the
112-
latest and run.
113-
- While this is a possible usage, if you are actively developing your spec it is preferred you provide a local copy.
114-
- Skip generation based off:
115-
- Flags
116-
- No difference between the cache and local
117-
- And all the functionality provided previously.
136+
## Next Generation Features (v5.0+)
118137

119-
Your original workflow stay the same but there is a slight difference in the annotations.
138+
- **Spec Caching:** Automatically caches your OpenAPI spec for faster incremental builds.
139+
- **Remote Spec Support:** Pulls and caches remote specs; always fetches the latest version unless using a local copy.
140+
- **Smart Generation:** Skips code generation if there are no changes in the spec or based on flags.
141+
- **All previous features remain available.**
120142

121-
New:
143+
**Example:**
122144

123145
```dart
124146
@Openapi(
125-
additionalProperties:
126-
DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep..'),
127-
inputSpec:
128-
RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
147+
additionalProperties: DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny Depp'),
148+
inputSpec: RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
129149
typeMappings: {'Pet': 'ExamplePet'},
130150
generatorName: Generator.dio,
131151
runSourceGenOnOutput: true,
@@ -134,33 +154,57 @@ New:
134154
class Example {}
135155
```
136156

137-
## Known Issues
157+
---
138158

139-
Check out the known issues article here [Known Issues](openapi-generator-annotations/README.md#known-issues)
159+
## Advanced Configuration
140160

141-
## Contributing
161+
If you are having issues with the generated code, this is not an problem with this package and creating an issue here will not help solve it. Its best to [create the issue in the base OpenApi library](https://github.com/OpenAPITools/openapi-generator/issues) since this package is a wrapper around that library for ease of use with Flutter/dart.
142162

143-
All contributions are welcome. Please ensure to read through our [contributing guidelines](CONTRIBUTING.md) before
144-
sending your PRs.
163+
Below are some advanced configurations you may try.
145164

146-
## Features and bugs
165+
- **Custom Templates:**
166+
Use the `templateDirectory` parameter to specify a custom code generation template.
147167

148-
### Note:
168+
- **Type & Import Mappings:**
169+
Use `typeMappings` and `importMappings` to control how OpenAPI types and models are mapped in Dart.
149170

150-
Some issues may originate from the base OpenAPI Generator library rather than this Dart/Flutter wrapper. This library provides Dart-specific configuration and tools, but the actual code generation is handled by the underlying OpenAPI Generator.
171+
- **Reserved Words:**
172+
Use `reservedWordsMappings` to avoid conflicts with Dart reserved words.
151173

152-
If you encounter problems with the generated code (such as incorrect imports, unexpected code structure, or type mismatches), these are often caused by the base generator, not this wrapper. You may be able to resolve some of these issues by customizing the @Openapi() annotation options.
174+
**Example:**
175+
176+
```dart
177+
@Openapi(
178+
additionalProperties: DioProperties(pubName: 'custom_api', pubAuthor: 'Jane Doe'),
179+
inputSpec: InputSpec(path: 'openapi-spec.yaml'),
180+
generatorName: Generator.dio,
181+
templateDirectory: 'templates/dart',
182+
typeMappings: {'date': 'DateTime'},
183+
importMappings: {'DateTime': 'package:my_project/date_time.dart'},
184+
reservedWordsMappings: {'class': 'clazz'},
185+
outputDirectory: 'api/custom_api',
186+
)
187+
class CustomApi {}
188+
```
153189

154-
- **template**: Allows you to specify a custom code generation template, helping fix issues related to the structure or style of the generated code.
190+
---
155191

156-
- **importMappings**: Lets you map OpenAPI model names to custom Dart imports, which helps fix problems with incorrect or missing import statements in the generated code.
192+
## Troubleshooting
157193

158-
- **typeMappings**: Allows you to map OpenAPI schema types to your own Dart types, which is useful for resolving issues where generated classes don’t match your project’s types or when you need to substitute types for better compatibility.
194+
### Common Issues
159195

160-
If the issue is specifically with the generated code, please open your issue in the original OpenAPI Generator repository.
196+
- **Dependency Conflicts:**
197+
Use `dependency_overrides` in the generated package's `pubspec.yaml` and add `pubspec.yaml` to `.openapi-generator-ignore` to prevent overwrites.
161198

162-
If you’re unsure where the problem comes from, feel free to open an issue here—we’ll help point you in the right direction.
199+
- **Incorrect Generated Code:**
200+
- Fix your OpenAPI spec (preferred).
201+
- Manually edit the generated code and add the files to `.openapi-generator-ignore` to prevent them from being overwritten.
163202

164-
Please file feature requests and bugs at the [issue tracker][tracker].
203+
**.openapi-generator-ignore Example:**
165204

166-
[tracker]: https://github.com/gibahjoe/openapi-generator-dart/issues
205+
```gitignore
206+
# Ignore all test files
207+
test/*
208+
# Ignore pubspec.yaml to preserve manual changes
209+
pubspec.yaml
210+
```

0 commit comments

Comments
 (0)