You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+7-6Lines changed: 7 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,12 +2,10 @@
2
2
3
3
## Before submitting an issue
4
4
5
+
- If you're not using the latest master to generate API clients or server stubs, please give it another try by pulling the latest master as the issue may have already been addressed. Ref: [Getting Started](https://github.com/swagger-api/swagger-codegen#getting-started)
5
6
- Search the [open issue](https://github.com/swagger-api/swagger-codegen/issues) and [closed issue](https://github.com/swagger-api/swagger-codegen/issues?q=is%3Aissue+is%3Aclosed) to ensure no one else has reported something similar before.
6
-
- The issue should contain details on how to repeat the issue, e.g.
7
-
- the OpenAPI Spec for reproducing the issue (:bulb: use [Gist](https://gist.github.com) to share). If the OpenAPI Spec cannot be shared publicly, it will be hard for the community to help
8
-
- version of Swagger Codegen
9
-
- language (`-l` in the command line, e.g. java, csharp, php)
10
-
- You can also make a suggestion or ask a question by opening an "issue"
7
+
- File an [issue ticket](https://github.com/swagger-api/swagger-codegen/issues/new) by providing all the required information.
8
+
- You can also make a suggestion or ask a question by opening an "issue".
11
9
12
10
## Before submitting a PR
13
11
@@ -42,11 +40,14 @@ Code change should conform to the programming style guide of the respective lang
You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those.
49
46
47
+
For [Vendor Extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#vendorExtensions), please follow the naming convention below:
48
+
- For general vendor extension, use lower case and hyphen. e.g. `x-is-unique`, `x-content-type`
49
+
- For language-specified vendor extension, put it in the form of `x-{lang}-{extension-name}`. e.g. `x-objc-operation-id`, `x-java-feign-retry-limit`
50
+
50
51
### Testing
51
52
52
53
To add test cases (optional) covering the change in the code generator, please refer to [modules/swagger-codegen/src/test/java/io/swagger/codegen](https://github.com/swagger-api/swagger-codegen/tree/master/modules/swagger-codegen/src/test/java/io/swagger/codegen)
@@ -386,8 +386,66 @@ To control the specific files being generated, you can pass a CSV list of what y
386
386
-Dmodels=User -DsupportingFiles=StringUtil.java
387
387
```
388
388
389
+
To control generation of docs and tests for api and models, pass false to the option. For api, these options are `-DapiTest=false` and `-DapiDocs=false`. For models, `-DmodelTest=false` and `-DmodelDocs=false`.
390
+
These options default to true and don't limit the generation of the feature options listed above (like `-Dapi`):
391
+
392
+
```
393
+
# generate only models (with tests and documentation)
394
+
java -Dmodels {opts}
395
+
396
+
# generate only models (with tests but no documentation)
397
+
java -Dmodels -DmodelDocs=false {opts}
398
+
399
+
# generate only User and Pet models (no tests and no documentation)
400
+
java -Dmodels=User,Pet -DmodelTests=false {opts}
401
+
402
+
# generate only apis (without tests)
403
+
java -Dapis -DapiTests=false {opts}
404
+
405
+
# generate only apis (modelTests option is ignored)
406
+
java -Dapis -DmodelTests=false {opts}
407
+
```
408
+
389
409
When using selective generation, _only_ the templates needed for the specific generation will be used.
390
410
411
+
### Ignore file format
412
+
413
+
Swagger codegen supports a `.swagger-codegen-ignore` file, similar to `.gitignore` or `.dockerignore` you're probably already familiar with.
414
+
415
+
The ignore file allows for better control over overwriting existing files than the `--skip-overwrite` flag. With the ignore file, you can specify individual files or directories can be ignored. This can be useful, for example if you only want a subset of the generated code.
416
+
417
+
Examples:
418
+
419
+
```
420
+
# Swagger Codegen Ignore
421
+
# Lines beginning with a # are comments
422
+
423
+
# This should match build.sh located anywhere.
424
+
build.sh
425
+
426
+
# Matches build.sh in the root
427
+
/build.sh
428
+
429
+
# Exclude all recursively
430
+
docs/**
431
+
432
+
# Explicitly allow files excluded by other rules
433
+
!docs/UserApi.md
434
+
435
+
# Recursively exclude directories named Api
436
+
# You can't negate files below this directory.
437
+
src/**/Api/
438
+
439
+
# When this file is nested under /Api (excluded above),
440
+
# this rule is ignored because parent directory is excluded by previous rule.
441
+
!src/**/PetApiTests.cs
442
+
443
+
# Exclude a single, nested file explicitly
444
+
src/IO.Swagger.Test/Model/AnimalFarmTests.cs
445
+
```
446
+
447
+
The `.swagger-codegen-ignore` file must exist in the root of the output directory.
448
+
391
449
### Customizing the generator
392
450
393
451
There are different aspects of customizing the code generator beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, etc:
0 commit comments