{"id":19990455,"url":"https://github.com/Orange-OpenSource/angular-swagger-ui","last_synced_at":"2025-05-04T09:35:43.456Z","repository":{"id":27977170,"uuid":"31470522","full_name":"Orange-OpenSource/angular-swagger-ui","owner":"Orange-OpenSource","description":"An angularJS implementation of Swagger UI","archived":true,"fork":false,"pushed_at":"2021-01-18T16:31:07.000Z","size":760,"stargazers_count":136,"open_issues_count":8,"forks_count":74,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-17T14:13:21.188Z","etag":null,"topics":["angular","api","api-documentation","api-rest","openapi","openapi3","swagger","swagger-ui","swagger1","swagger2"],"latest_commit_sha":null,"homepage":"http://orange-opensource.github.io/angular-swagger-ui/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Orange-OpenSource.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-28T17:44:11.000Z","updated_at":"2024-11-29T17:18:55.000Z","dependencies_parsed_at":"2022-08-31T00:31:06.723Z","dependency_job_id":null,"html_url":"https://github.com/Orange-OpenSource/angular-swagger-ui","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-OpenSource%2Fangular-swagger-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-OpenSource%2Fangular-swagger-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-OpenSource%2Fangular-swagger-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Orange-OpenSource%2Fangular-swagger-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Orange-OpenSource","download_url":"https://codeload.github.com/Orange-OpenSource/angular-swagger-ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252317000,"owners_count":21728521,"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":["angular","api","api-documentation","api-rest","openapi","openapi3","swagger","swagger-ui","swagger1","swagger2"],"created_at":"2024-11-13T04:51:14.919Z","updated_at":"2025-05-04T09:35:43.029Z","avatar_url":"https://github.com/Orange-OpenSource.png","language":"JavaScript","readme":"# angular-swagger-ui\n\n`angular-swagger-ui` is an angularJS implementation of OpenAPI UI\n\n[OpenAPI](https://www.openapis.org) (aka [Swagger](https://swagger.io)) helps you documenting your RESTful API.\n\nOpenAPI UI helps developers discovering your RESTful API by providing an online documentation with an integrated API explorer.\n\n### Warning \n\u003e By default, only OpenAPI 2.0 is supported.\nTo handle OpenAPI 3.0.0 please add module `openapi3-converter` see [Enable OpenAPI 3.0.0](#enable-openapi-300).\nTo handle OpenAPI 1.2 please add module `swagger1-converter` see [Enable OpenAPI 1.2](#enable-openapi-12).\nTo handle authorization please add module `swagger-auth` see [Enable authorization](#enable-authorization)\nTo handle YAML please add module `swagger-yaml-parser` see [Enable YAML](#enable-yaml)\n\n## Demo\n\nA sample app using `angular-swagger-ui` is available here:\n\nhttp://orange-opensource.github.io/angular-swagger-ui\n\n## Quick Start\n\n### Install\n\n`npm install angular-swagger-ui`\n\n### Dependencies\n\n1. [angularJS](https://angularjs.org)\n2. [bootstrap CSS](http://getbootstrap.com)\n3. [angular-ui-bootstrap](https://angular-ui.github.io/bootstrap/) (required only if using [Authorization](#enable-authorization))\n\n## License\n\nAll code in this repository is covered by the [MIT license](http://opensource.org/licenses/MIT).\nSee LICENSE file for copyright details.\n\n## Getting Started\n\nInclude `angular-swagger-ui` as a dependency into your application\n\nAs some properties of OpenAPI specifications can be formatted as HTML:\n\n* You **SHOULD** include `ngSanitize` as a dependency into your application (avoids JS injection) if OpenAPI specifications are loaded from **untrusted** sources (see `dist/index.html` as an example)\n* You **CAN** add `trusted-sources=\"true\"` as directive parameter (avoids embedding `ngSanitize`) if OpenAPI specifications are loaded from **trusted** sources (see `src/index.html` as an example)\n* You **MUST** at least choose one of the two previous solutions\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n\t// If directive has parameter trusted-sources=\"true\"\n\tangular.module('yourApp', ['swaggerUi']);\n\t...\n\t// OR if you choosed to use \"ngSanitize\"\n\tangular.module('yourApp', ['ngSanitize', 'swaggerUi']);\n\t...\n\u003c/script\u003e\n```\nCreate an HTML element in your angularJS application's template or in your HTML page\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" api-explorer=\"true\"\u003e\u003c/div\u003e\n```\nAdd `swagger-ui.min.js` and `angular.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003c!-- if you choosed to use \"ngSanitize\" --\u003e\n \t\u003cscript src=\"yourPathToAngularSanitize/angular-sanitize.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\nAdd `swagger-ui.min.css` and `bootstrap.min.css` to the head of the HTML page.\n```html\n\u003cbody\u003e\n\t\u003chead\u003e\n\t\t...\n\t\t\u003clink rel=\"stylesheet\" href=\"yourPathToBootstrapCSS/bootstrap.min.css\"\u003e\n\t\t\u003clink rel=\"stylesheet\" href=\"yourPathToAngularSwaggerUI/dist/css/swagger-ui.min.css\"\u003e\n  \t\u003c/head\u003e\n\u003c/body\u003e\n```\n\n## Parameters\n\n#### API explorer\nDisplay or not API explorer, default is `false`\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" api-explorer=\"true/false\"\u003e\u003c/div\u003e\n```\n\n#### OpenAPI specification loading indicator\n`yourScopeVariable` will be assigned to `true` or `false` depending on OpenAPI specification loading status\n```html\n\u003cdiv ng-show=\"yourScopeVariable\"\u003eloading ...\u003c/div\u003e\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" loading=\"yourScopeVariable\"\u003e\u003c/div\u003e\n```\n\n#### Error handler\nDefine an error handler to catch errors, if none defined `console.error` is used\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" error-handler=\"yourErrorHandler\"\u003e\u003c/div\u003e\n```\n```js\n$scope.yourErrorHandler = function(/*String or Object*/ message, /*Integer*/ code){\n\t\n}\n```\n\n#### Permalinks\nAllows having a URL direct access to a group of operations or to an operation and making it unfolded at startup\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" permalinks=\"true/false\"\u003e\u003c/div\u003e\n```\n\n#### Download\nDisplay or not a link to download swagger file. \n\n```html\n\u003c!-- display link with url label --\u003e\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" download\u003e\u003c/div\u003e\n\n\u003c!-- display link with specific key enter in swaggerTranslatorProvider --\u003e\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" download=\"downloadLabel\"\u003e\u003c/div\u003e\n```\n\n#### OpenAPI validator\nDisable OpenAPI validator or define a custom OpenAPI validator.\nIf parameter not defined, the validator will be 'http://online.swagger.io/validator'\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" validator-url=\"false or URL\"\u003e\u003c/div\u003e\n```\n\n#### Parser type\nOpenAPI specification parser is chosen depending on the `Content-Type` of the specification response. If host serving your OpenAPI specification does not send `Content-Type: application/json` then you can force the parser to JSON:\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" parser=\"json\"\u003e\u003c/div\u003e\n```\n\n#### Template URL\nDefine a custom template to be used by OpenAPIUI\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" template-url=\"yourTemplatePath\"\u003e\u003c/div\u003e\n```\n\n#### Inherited properties\nAllows displaying inherited properties of polymorphic models\n```html\n\u003cdiv swagger-ui url=\"URLToYourOpenAPISpecification\" show-inherited-properties=\"true/false\"\u003e\u003c/div\u003e\n```\n\n#### Input type and input\n##### Render an OpenAPI specification from JSON object\n```html\n\u003cdiv swagger-ui input-type=\"json\" input=\"yourJsonObject\"\u003e\u003c/div\u003e\n```\n\n##### Render an OpenAPI specification from YAML string\nMake sure to use module `swagger-yaml-parser`, see [Enable YAML](#enable-yaml)\n```html\n\u003cdiv swagger-ui input-type=\"yaml\" input=\"yourYamlString\"\u003e\u003c/div\u003e\n```\n\n##### Render an OpenAPI specification from URL (same behavior as using \"url\" parameter)\n```html\n\u003cdiv swagger-ui input-type=\"url\" input=\"yourURL\"\u003e\u003c/div\u003e\n```\n\n## i18n\n\n#### Built-in languages\n`angular-swagger-ui` is available in english and french, english is used by default\n\nTo use french, add `fr.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/i18/fr.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\nSet language to french at startup\n```html\n\u003cscript type=\"text/javascript\"\u003e\n\tangular\n\t\t.module('yourApp', ['swaggerUi'])\n\t\t.config(function(swaggerTranslatorProvider) {\n\t\t\tswaggerTranslatorProvider.setLanguage('fr');\n\t\t});\n\t...\n\u003c/script\u003e\n```\nSet language to french at runtime\n```html\n\u003cscript type=\"text/javascript\"\u003e\n\tangular\n\t\t.module('yourApp', ['swaggerUi'])\n\t\t.controller('yourController', function(swaggerTranslator) {\n\t\t\tswaggerTranslator.useLanguage('fr');\n\t\t});\n\t...\n\u003c/script\u003e\n```\n\n#### Add languages\nYou can add your own languages, see `src/scripts/i18n/en.js` to find the keys you have to override\n```html\n\u003cscript type=\"text/javascript\"\u003e\n\tangular\n\t\t.module('yourApp', ['swaggerUi'])\n\t\t.config(function(swaggerTranslatorProvider) {\n\t\t\tswaggerTranslatorProvider.addTranslations('yourLangId', {\n\t\t\t\tkey: 'value'\n\t\t\t\t...\n\t\t\t});\n\t\t\tswaggerTranslatorProvider.setLanguage('yourLangId');\n\t\t});\n\t...\n\u003c/script\u003e\n```\n\n#### Internationalize your app\nYou can also use `swaggerTranslator` to internationalize your app by using a service, a directive or a filter\n```html\n\u003cbody\u003e\n \t...\n \t\u003cdiv swagger-translate=\"yourKey\" swagger-translate-value=\"yourParam\"\u003e\u003c/div\u003e\n \t\u003cdiv ng-bind=\"yourDynamicKey|swaggerTranslate:yourDynamicParam\"\u003e\u003c/div\u003e\n \t...\n\t\u003cscript type=\"text/javascript\"\u003e\n\t\tangular\n\t\t\t.module('yourApp', ['swaggerUi'])\n\t\t\t.config(function(swaggerTranslatorProvider) {\n\t\t\t\tswaggerTranslatorProvider.addTranslations('en', {\n\t\t\t\t\tyourKey: 'blablabla {{propertyNameOfYourParam}}'\n\t\t\t\t\t...\n\t\t\t\t});\n\t\t\t})\n\t\t\t.controller('yourController', function(swaggerTranslator) {\n\t\t\t\tvar localizedMessage = swaggerTranslator.translate('yourKey', yourParam);\n\t\t\t});\n\t\t...\n\t\u003c/script\u003e\n\u003c/body\u003e\n```\n\n## Customization\n\n#### Enable OpenAPI 3.0.0\nSee [OpenAPI 3.0.0 spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md).\nAdd `openapi3-converter.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/openapi3-converter.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable authorization\n`oauth` is not implemented, only `basic` and `API key` authorizations are implemented.\nAdd `swagger-auth.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth.min.js\"\u003e\u003c/script\u003e\u003c!-- without angular-ui-bootstrap modal embedded --\u003e\n \tOR\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth-ui-boostrap-modal.min.js\"\u003e\u003c/script\u003e\u003c!-- angular-ui-bootstrap modal embedded --\u003e\n \t...\n\t\u003cscript type=\"text/javascript\"\u003e\n\t\tangular\n\t\t\t.module('yourApp', ['swaggerUi', 'swaggerUiAuthorization'])\n\t\t\t// what is below is required for oauth2 flows 'implicit' and 'accessCode' (ie. authorizationCode)\n\t\t\t// what is below can also be used to initialize apiKey or Basic authorizations\n      .config(function(swaggerUiAuthProvider) {\n          swaggerUiAuthProvider.configuration({\n              // required for oauth2 flow 'implicit' and 'accessCode' (ie. authorizationCode)\n             \tredirectUrl: 'yourPathToAngularSwaggerUI/oauth2-redirect.html' \n              // optional\n              yourSecurityName: {\n              \tapiKey: 'yourApiKeyValue' // optional, can be used to initialize api key value\n              },\n              // optional\n              yourSecurityName: {\n              \tlogin: 'yourLogin', // optional, can be used to initialize basic login\n              \tpassword: 'yourPassword' // optional, can be used to initialize basic password\n              },\n              // optional\n              yourSecurityName: {\n              \tclientId: 'yourClientId', // optional, can be used to initialize oauth2 credentials\n              \tclientSecret: 'yourClientSecret', // optional, can be used to initialize oauth2 credentials\n              \tlogin: 'yourLogin', // optional, can be used to initialize oauth2 credentials\n              \tpassword: 'yourPassword', // optional, can be used to initialize oauth2 credentials\n              \tscopeSeparator: 'scopeSeparator', // optional, can be used to configure oauth2 scopes separator, default value is space\n              \t// optional, can be used to configure oauth2 additional query params to tokenUrl and authorizationUrl\n              \tqueryParams: {\n              \t\t'yourQueryParamName': 'yourQueryParamValue'\n              \t\t...\n              \t}, \n              },\n          });\n      })\n\t\t\t...\n\t\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable OpenAPI [aka Swagger] 1.2\nSee [OpenAPI 1.2 spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md).\nAdd `swagger1-converter.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger1-converter.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable OpenAPI external references\nSee [OpenAPI 2.0 spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#relative-schema-file-example).\nAdd `swagger-external-references.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-external-references.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable XML formatter on API explorer responses\nAdd `swagger-xml-formatter.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-xml-formatter.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable YAML\nAdd [js-yaml library](https://cdnjs.com/libraries/js-yaml).\nAdd `swagger-yaml-parser.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToJsYaml/js-yaml.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-yaml-parser.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Enable markdown\nAdd [marked library](https://cdnjs.com/libraries/marked).\nAdd `swagger-markdown.min.js` at the end of the body\n```html\n\u003cbody\u003e\n \t...\n \t\u003cscript src=\"yourPathToAngularJS/angular.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToMarked/marked.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js\"\u003e\u003c/script\u003e\n \t\u003cscript src=\"yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-markdown.min.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n```\n\n#### Writing your own modules\nModifying `angular-swagger-ui` can be achieved by writing your own modules. As an example your can have a look at the ones in `src/scripts/modules`.\nA module is an object (can be a service) having a function `execute` which must return a promise.\n\nYou can make your module modifying behaviours at different phases:\n\n* `BEFORE_LOAD`: allows modifying OpenAPI specification request before it is sent\n* `BEFORE_PARSE`: allows modifying OpenAPI specification after it has been loaded\n* `PARSE`: allows adding an OpenAPI parser for content types other than JSON\n* `BEFORE_DISPLAY`: allows modifying internal parsed OpenAPI specification before it is displayed\n* `BEFORE_EXPLORER_LOAD`: allows modifying API explorer request before it is sent\n* `AFTER_EXPLORER_LOAD`: allows modifying API explorer response before it is displayed\n\n```js\nangular\n\t.module('myApp', ['swaggerUi'])\n\t.service('myModule', function($q) {\n\n\t\tthis.execute = function(data) {\n\t\t\tvar deferred = $q.defer();\n\t\t\t// if nothing done: call deferred.resolve(false);\n\t\t\t// if success: call deferred.resolve(true);\n\t\t\t// if error: call deferred.reject({message: 'error message', code: 'error_code'});\n\t\t\treturn deferred.promise;\n\t\t}\n\n\t})\n\t.run(function(swaggerModules, myModule){\n\t\t// default priority is 1\n\t\t// higher is the priority, sooner the module is executed at the specified phase\n\t\tswaggerModules.add(swaggerModules.BEFORE_LOAD, myModule, priority);\n\t})\n\t...\n\n```\n","funding_links":[],"categories":["JavaScript","Service"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrange-OpenSource%2Fangular-swagger-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOrange-OpenSource%2Fangular-swagger-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrange-OpenSource%2Fangular-swagger-ui/lists"}