<commit_before># Swagger Doclet 

[![Build Status](https://travis-ci.org/teamcarma/swagger-jaxrs-doclet.svg?branch=master)](https://travis-ci.org/teamcarma/swagger-jaxrs-doclet)

This is a JavaDoc Doclet that can be used to generate a JSON Swagger resource listing suitable for feeding to the Swagger UI. It generates the resource listing from the source code of java JAXRS resources and entities.

This was originally forked from [<NAME>'s original doclet](https://github.com/ryankennedy/swagger-jaxrs-doclet) to add support for swagger 1.2 and has moved on considerably from it.

This is used as a basis for the [Carma API Reference](https://api-dev.car.ma/apidoc/ref/index.html) which is a good working example of the Swagger UI being used for a large API.

#####Note you can win [$1,000,000](http://carmacarpool.com/prize) using the Carma API! 


##Why Use This Doclet?

+ As the JSON resource listing  is generated offline from source code it means that you do not need to add any runtime dependencies to your project and avoid potential headaches with different jar versions and jaxrs implementations. This also avoids increasing the size of your artifacts. 
+ The offline approach also allows you to post process the JSON if you wish. 
+ You also do not need to add any Swagger specific annotations to your source code as you can fine tune the generated documentation using javadoc tags.

## Versions

1.1.x Versions and higher require Java 8

1.0.x Versions require Java 6/7

The latest fork version is 1.1.0.8, the latest upstream version is 1.1.1.

Fork version 1.1.0.8:
+ fix infinite loop in swagger-doclet when using recursive @JsonSubTypes

Fork version 1.1.0.7:
+ fix NPE with extraApiDeclarations without Models
+ apiPath of included extraApiDeclarations is now ignored
+ fix some quirks in swagger-ui regarding the urls

Fork version 1.1.0.6:
+ Disabled online swagger-validator because intranet unreachable from internet

Fork version 1.1.0.5:
+ 1and1-branded UI (1and1-blue, removed swagger-links)
+ QualityOfLife-Improvements in the UI (fullscreen, expandAll, scrollbars instead of truncations)
+ simplify patching the included UI by generated ui-overrides.zip
+ Inherit Resource-@Path from baseclasses (https://github.com/teamcarma/swagger-jaxrs-doclet/pull/100)
+ Merge Operations with same parameters and return-types but differing mime-types (For RestResource-Methods differing only in response-mimetype) (https://github.com/teamcarma/swagger-jaxrs-doclet/pull/101)
+ additional (not annotated) headerParams can be documented by commandline-parameters. (Will not support MatrixParameters. Use Header "Cookie: JSESSIONID=..." instead).
```
<additionalparam>
  -additionalHeaderParam X-UI-APP
  -additionalHeaderParam My-Test-Version=1.2.3
</additionalparam>
```
+ swagger-specs of other maven-submodules can be added
```<commit_msg>v. 1.1.1.0<commit_after># Swagger Doclet 

[![Build Status](https://travis-ci.org/teamcarma/swagger-jaxrs-doclet.svg?branch=master)](https://travis-ci.org/teamcarma/swagger-jaxrs-doclet)

This is a JavaDoc Doclet that can be used to generate a JSON Swagger resource listing suitable for feeding to the Swagger UI. It generates the resource listing from the source code of java JAXRS resources and entities.

This was originally forked from [Ryan Kennedy's original doclet](https://github.com/ryankennedy/swagger-jaxrs-doclet) to add support for swagger 1.2 and has moved on considerably from it.

This is used as a basis for the [Carma API Reference](https://api-dev.car.ma/apidoc/ref/index.html) which is a good working example of the Swagger UI being used for a large API.

#####Note you can win [$1,000,000](http://carmacarpool.com/prize) using the Carma API! 


##Why Use This Doclet?

+ As the JSON resource listing  is generated offline from source code it means that you do not need to add any runtime dependencies to your project and avoid potential headaches with different jar versions and jaxrs implementations. This also avoids increasing the size of your artifacts. 
+ The offline approach also allows you to post process the JSON if you wish. 
+ You also do not need to add any Swagger specific annotations to your source code as you can fine tune the generated documentation using javadoc tags.

## Versions

1.1.x Versions and higher require Java 8

1.0.x Versions require Java 6/7

The latest fork version is 1.1.1.0, the latest upstream version is 1.1.1.

Fork version 1.1.1.0:
+ replace swagger-ui-2.1.0 with 2.1.8-M1 release, because model classes are not documented properly and some methods are not shown (DEVMMAIC-1157, DEVMMAIC-1195)

Fork version 1.1.0.8:
+ fix infinite loop in swagger-doclet when using recursive @JsonSubTypes

Fork version 1.1.0.7:
+ fix NPE with extraApiDeclarations without Models
+ apiPath of included extraApiDeclarations is now ignored
+ fix some quirks in swagger-ui regarding the urls

Fork version 1.1.0.6:
+ Disabled online swagger-validator because intranet unreachable from internet

Fork version 1.1.0.5:
+ 1and1-branded UI (1and1-blue, removed swagger-links)
+ QualityOfLife-Improvements in the UI (fullscreen, expandAll, scrollbars instead of truncations)
+ simplify patching the included UI by generated ui-overrides.zip
+ Inherit Resource-@Path from baseclasses (https://github.com/teamcarma/swagger-jaxrs-doclet/pull/100)
+ Merge Operations with same parameters and return-types but differing mime-types (For RestResource-Methods differing only in response-mimetype) (https://github.com/teamcarma/swagger-jaxrs-doclet/pull/101)
+ additional (not annotated) headerParams can be documented by commandline-parameters. (Will not support MatrixParameters. Use Header "Cookie: JSESSIONID=..." instead).
```
<additionalparam>
  -additionalHeaderParam X-UI-APP
  -additionalHeaderParam My-Test-Version=1.2.3
</additionalparam>
```
+ swagger-specs of other maven-submodules can be added
```
{'fraction_non_alphanumeric': 0.08036622583926754, 'fraction_numerical': 0.021532722956934553, 'mean_word_length': 4.618095238095238, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 8, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 12, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4342255', 'n_tokens_mistral': 1818, 'n_tokens_neox': 1709, 'n_words': 707}