{"id":17948244,"url":"https://github.com/phillip-kruger/apiee","last_synced_at":"2025-05-07T13:46:13.547Z","repository":{"id":54357137,"uuid":"92584746","full_name":"phillip-kruger/apiee","owner":"phillip-kruger","description":"Swagger documentation for Java EE projects","archived":false,"fork":false,"pushed_at":"2024-09-05T23:45:31.000Z","size":840,"stargazers_count":50,"open_issues_count":0,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T09:03:40.511Z","etag":null,"topics":["java-library","javaee","openapi","swagger","swagger-ui"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phillip-kruger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-27T08:37:33.000Z","updated_at":"2024-09-06T07:37:30.000Z","dependencies_parsed_at":"2024-08-27T01:51:20.008Z","dependency_job_id":"f6118219-d2b7-4424-919b-9655e991edf4","html_url":"https://github.com/phillip-kruger/apiee","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phillip-kruger%2Fapiee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phillip-kruger%2Fapiee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phillip-kruger%2Fapiee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phillip-kruger%2Fapiee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phillip-kruger","download_url":"https://codeload.github.com/phillip-kruger/apiee/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252890003,"owners_count":21820287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java-library","javaee","openapi","swagger","swagger-ui"],"created_at":"2024-10-29T09:03:45.631Z","updated_at":"2025-05-07T13:46:13.503Z","avatar_url":"https://github.com/phillip-kruger.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Apiee\n\n\u003e Easy Swagger and Swagger UI in Java EE.\n\n[![Build Status](https://travis-ci.org/phillip-kruger/apiee.svg?branch=master)](https://travis-ci.org/phillip-kruger/apiee)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.phillip-kruger/apiee/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.phillip-kruger/apiee)\n[![License](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://raw.githubusercontent.com/phillip-kruger/apiee/master/LICENSE.txt)\n[![Javadocs](https://www.javadoc.io/badge/com.github.phillip-kruger/apiee-core.svg)](https://www.javadoc.io/doc/com.github.phillip-kruger/apiee-core)\n\n![logo](https://raw.githubusercontent.com/phillip-kruger/apiee/master/apiee-core/src/main/webapp/apiee/logo.png) \n\n\u003e apiee@phillip-kruger.com\n\n[![Twitter URL](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](https://twitter.com/phillipkruger)\n\n***\n## Quick Start\nApiee creates swagger documentation from your JAX-RS and Swagger annotations in Runtime. It also give you a custom Swagger UI screen.\n \nThe apiee-core library is published to [maven central](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22apiee-core%22) and artefacts is available in [Nexus OSS](https://oss.sonatype.org/#nexus-search;quick~apiee-core)\n\nIn your pom.xml:\n \n     \u003c!-- Apiee --\u003e\n     \u003cdependency\u003e\n            \u003cgroupId\u003ecom.github.phillip-kruger\u003c/groupId\u003e\n            \u003cartifactId\u003eapiee-core\u003c/artifactId\u003e\n            \u003cversion\u003e1.0.8\u003c/version\u003e\n     \u003c/dependency\u003e\n\nIn you JAX-RS Application class:\n\n    @ApplicationPath(\"/api\")\n    @SwaggerDefinition (info = @Info (\n                        title = \"Example Service\",\n                        description = \"A simple example of apiee\",\n                        version = \"1.0.0\",\n                        contact = @Contact (\n                            name = \"Phillip Kruger\", \n                            email = \"apiee@phillip-kruger.com\", \n                            url = \"http://phillip-kruger.com\"\n                        )\n                    )\n                )\n    public class ApplicationConfig extends Application {\n\n    }\n\nYou can also set the `@SwaggerDefinition` part in `apiee.properties` (more about that later)\n\nIn your JAX-RS Endpoint class:\n\n    @Path(\"/example\")\n    @Produces({MediaType.APPLICATION_JSON}) \n    @Consumes({MediaType.APPLICATION_JSON})\n    @Api(value = \"Example service\")\n    @Log\n    public class ExampleService {\n        \n        @GET\n        @ApiOperation(value = \"Retrieve some example content\", notes = \"This will return some json to the client\",response = JsonObject.class)\n        public Response getExample(){\n            JsonObject jsonObject = Json.createObjectBuilder().add(\"name\", \"apiee example\").add(\"url\", \"https://github.com/phillip-kruger/apiee-example\").build();\n            log.log(Level.INFO, \"GET: {0}\", jsonObject);\n            return Response.ok(jsonObject).build();\n        }\n    }\n\nYou can then go to the apiee swagger-ui :\n\u003e http://localhost:8080/your-application-context/your-jaxrs-application-path/apiee/\n\n## Security\nYou can add security using the normal Swagger annotation, or some properties in apiee.properties or a combination of both.\n\n### Basic Auth example:\n\n#### As annotation:\n\n    @SwaggerDefinition (securityDefinition = \n        @SecurityDefinition(basicAuthDefinitions = @BasicAuthDefinition(key = \"basic\",description = \"foo\"))\n    )\n\n#### Or in apiee.properties:\n\n    securityBasicAuthKey=basic\n    securityBasicAuthDesc=foo # Optional\n\n### API Key example\n\n#### As annotation:\n\n    @SwaggerDefinition (securityDefinition = \n        @SecurityDefinition(apiKeyAuthDefinitions = @ApiKeyAuthDefinition(key = \"api\" , name=\"Authorization\", in = ApiKeyAuthDefinition.ApiKeyLocation.HEADER))\n    )\n\n#### Or in apiee.properties:\n    \n    securityApiKeyKey=Bearer\n    securityApiKeyIn=HEADER # Optional. Default is HEADER. (HEADER/QUERY)\n    securityApiKeyDesc=foo # Optional\n    securityApiKeyName=Authorization # Optional. Authorization\n\n### OAuth 2 example\n\n#### As annotation:\n\n    @SwaggerDefinition (securityDefinition = \n        @SecurityDefinition(oAuth2Definitions = @OAuth2Definition(key=\"oauth2\",\n                                    authorizationUrl = \"/auth\",\n                                    description = \"Bla bla bla\",\n                                    flow = OAuth2Definition.Flow.PASSWORD,\n                                    scopes = @Scope(name = \"scopename\",description = \"the scope\"),\n                                    tokenUrl = \"/auth/token\"))\n    )\n\n#### Or in apiee.properties:\n\n    securityOAuth2Key=oauth2\n    securityOAuth2AuthUrl=/auth\n    securityOAuth2TokenUrl=/auth/token\n    securityOAuth2Flow=PASSWORD # One of ACCESS_CODE,APPLICATION,IMPLICIT,PASSWORD\n    securityOAuth2Scopes=scopename:the scope,anotherName:the other scope # Comma-seperated with name:description\n    securityOAuth2Desc=bla bla bla\n\n![](https://raw.githubusercontent.com/phillip-kruger/apiee/master/Screenshot5.png)\n(above: an API key example)\n\n## Whitelabel\nApiee comes out of the box with it's own themed swagger ui. However, you might not want a monkey's face on you \nAPI documentation, so Apiee makes it easy to whitelabel the UI.\n\n![](https://raw.githubusercontent.com/phillip-kruger/apiee/master/Screenshot1.png)\n(above: default theme out-of-the-box)\n\nIn your web app `/src/main/resources` you can include the following files:\n* apiee.properties\n* apiee.png\n* apiee.css\n* apiee.html\n\n### Variables (apiee.properties)\nThe HTML template that creates the Swagger UI has some variables that you can define in a properties\n\u003e     copyrighBy=John Smith\n\u003e     title=Company X\n\u003e     jsonButtonCaption=download json\n\u003e     yamlButtonCaption=download yaml\n\u003e     swaggerUiTheme=monokai \n\nThere are also some [Swagger UI parameters](https://github.com/swagger-api/swagger-ui/tree/v2.2.10#parameters) (with default values) that you can include changing (below contains the default values):\n\n\u003e     supportedSubmitMethods=['get', 'post', 'put', 'delete']\n\u003e     docExpansion=none\n\u003e     jsonEditor=true\n\u003e     defaultModelRendering=scheme\n\u003e     showRequestHeaders=true\n\u003e     showOperationIds=false\n\u003e     validatorUrl=null\n\nAnd some OAuth parameters (below contains the default values):\n\n\u003e     oauthClientId=your-client-id\n\u003e     oauthClientSecret=your-client-secret-if-required\n\u003e     oauthRealm=your-realms\n\u003e     oauthAppName=your-app-name\n\u003e     oauthScopeSeparator=\n\nIf you want more customization, you can include your own template (apiee.html), see Template section below.  \n\nYou can also define the `@SwaggerDefinition` in the `apiee.properties` with the following properties (so then you can omit it from the source code annotation). NOTE: all properties are optional.\n\n\u003e     infoTitle=Company X Services\n\u003e     infoDescription=REST API of Company X\n\u003e     infoVersion=1.0.1\n\u003e     infoContactName=Phillip Kruger\n\u003e     infoContactEmail=apiee@phillip-kruger.com\n\u003e     infoContactUrl=http://phillip-kruger.com\n\u003e     infoLicenseName=Apache License, Version 2.0\n\u003e     infoLicenseUrl=http://www.apache.org/licenses/LICENSE-2.0\n\u003e     infoTermsOfService=Some terms here\n\u003e     consumes=application/json,application/xml\n\u003e     produces=application/json\n\u003e     basePath=/api\n\u003e     schemes=HTTP,HTTPS # valid values: HTTP,HTTPS,WS,WSS\n\u003e     host=myhost.com # if ommited, will figure this out based on headers and server\n\u003e     tags=example:example description,foo,bar\n\n### Theme (apiee.css)\nApiee includes [swagger-ui-themes](http://meostrander.com/swagger-ui-themes/) and use the `muted` theme as default. You can override the theme by setting the `swaggerUiTheme` in the `apiee.properties` (see above). You can also include your own CSS called `apiee.css` to style the UI.\nThemes available from [swagger-ui-themes](http://meostrander.com/swagger-ui-themes/):\n* feeling-blue\n* flattop\n* material\n* monokai\n* muted\n* newspaper\n* outline\n\n![](https://raw.githubusercontent.com/phillip-kruger/apiee/master/Screenshot2.png)\n(above: some variables and theme changed)\n\n### Logo (apiee.png)\nTo replace the default monkey face logo, include the apiee.png file\n\n![](https://raw.githubusercontent.com/phillip-kruger/apiee/master/Screenshot3.png)\n(above: logo changed)\n\n### Template (apiee.html)\n(Advanced) Lastly, if you want even more customization, you can provide you own HTML template to override the default default.\nThis allows you to really change the Look and Feel of you Swagger UI\n\n![](https://raw.githubusercontent.com/phillip-kruger/apiee/master/Screenshot4.png)\n(above: custome html template)\n\n## Application Servers\nApiee has been tested using the following Java EE 7 application servers:\n\n* [Wildfly 10.0.1](http://wildfly.org/)\n* [Payara 172](http://www.payara.fish/)\n* [Liberty 17.0.0.1](https://developer.ibm.com/assets/wasdev/#asset/runtimes-wlp-javaee7)\n\n## Via a Proxy\nYou can set some headers to create the correct URL in swagger documents and to make the the UI works. This is handy if the request is going through a proxy.\n\n* x-request-uri (if this is set, the `path` part of the URL will be set to this)\n* x-forwarded-port (if this is set, the `port` part of the URL will be set to this)\n* x-forwarded-host (if this is set, the `host` part of the URL will be set to this)\n* x-forwarded-proto (if this is set, the `scheme` or `protocol` part of the URL will be set to this)\n\n## Cache\nThe generation of the swagger document happens at first request and are cached per url for the lifetime of the running server (Application Scoped)\n\nYou can clear the cache in the following ways:\n* Add a query parameter (clearCache=true) to the swagger UI URL, eg. http://localhost:8080/apiee-example/api/apiee/index.html?clearCache=true\n* Do a HTTP DELETE on http://localhost:8080/apiee-example/api/apiee/\n\nYou can also see the time that the document has been created in the footer of the swagger UI screen.\n\nOther usefull REST endpoints that might help with debugging:\n\n* HTTP GET on http://localhost:8080/apiee-example/api/apiee/generatedOn.json will return the generation details, eg:\n\n```json\n{\n  \"date\": \"Fri Apr 20 14:06:00 SAST 2018\",\n  \"formattedDate\": \"2018/04/20 2:06 PM\"\n}\n```\n\n* HTTP GET on http://localhost:8080/apiee-example/api/apiee/cacheMap.json will return the cached documents, eg:\n\n```json\n[\n  {\n    \"hash\": 1912183572,\n    \"generatedOn\": \"Fri Apr 20 14:06:00 SAST 2018\",\n    \"url\": \"http://localhost:8080/apiee-example/api/apiee/swagger.json\"\n  }\n]\n```\n\n## Blog entry\nAlso see [this blog](http://www.phillip-kruger.com/2017/06/apiee-easy-way-to-get-swagger-on-java-ee.html) entry\n\n**Documentation available here:** [https://github.com/phillip-kruger/apiee/wiki](https://github.com/phillip-kruger/apiee/wiki)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphillip-kruger%2Fapiee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphillip-kruger%2Fapiee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphillip-kruger%2Fapiee/lists"}