angular-swagger-ui is an angularJS implementation of Swagger UI
Swagger helps you documenting your RESTful API.
Swagger UI helps developers discovering your RESTful API by providing an online documentation with an integrated API explorer.
By default, only JSON Swagger 2.0 is supported. To handle Swagger 1.2 please add module
swagger1-to-swagger2-converter(beta) see enable Swagger 1.2
Authentication is not implemented, please use modules to customize API calls
A sample app using angular-swagger-ui is available here:
http://orange-opensource.github.io/angular-swagger-ui
bower install angular-swagger-ui --save
All code in this repository is covered by the MIT license. See LICENSE file for copyright details.
Include angular-swagger-ui as a dependency into your application
As some properties of Swagger descriptors can be formatted as HTML:
- You SHOULD include
ngSanitizeas a dependency into your application (avoids JS injection) if Swagger descriptors are loaded from untrusted sources (seedist/index.htmlas an example) - You CAN add
trusted-sources="true"as directive parameter (avoids embeddingngSanitize) if Swagger descriptors are loaded from trusted sources (seesrc/index.htmlas an example) - You MUST at least choose one of the two previous solutions
<script type="text/javascript">
// If directive has parameter trusted-sources="true"
angular.module('yourApp', ['swaggerUi']);
...
// OR if you choosed to use "ngSanitize"
angular.module('yourApp', ['ngSanitize', 'swaggerUi']);
...
</script>Create an HTML element in your angularJS application's template or in your HTML page
<div swagger-ui url="URLToYourSwaggerDescriptor" api-explorer="true"></div>Add swagger-ui.min.js and angular.min.js to the end of the body
<body>
...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<!-- if you choosed to use "ngSanitize" -->
<script src="yourPathToAngularSanitize/angular-sanitize.min.js"></script>
</body>Add swagger-ui.min.css and bootstrap.min.css to the head of the HTML page.
<body>
<head>
...
<link rel="stylesheet" href="yourPathToBootstrapCSS/bootstrap.min.css">
<link rel="stylesheet" href="yourPathToAngularSwaggerUI/dist/css/swagger-ui.min.css">
</head>
</body>Display or not API explorer, default is false
<div swagger-ui url="URLToYourSwaggerDescriptor" api-explorer="true/false"></div>yourScopeVariable will be assigned to true or false depending on Swagger descriptor loading status
<div ng-show="yourScopeVariable">loading ...</div>
<div swagger-ui url="URLToYourSwaggerDescriptor" loading="yourScopeVariable"></div>Define an error handler to catch errors, if none defined console.error is used
<div swagger-ui url="URLToYourSwaggerDescriptor" error-handler="yourErrorHandler"></div>$scope.yourErrorHandler = function(/*String or Object*/ message, /*Integer*/ code){
}Allows having a URL direct access to a group of operations or to an operation and making it unfolded at startup
<div swagger-ui url="URLToYourSwaggerDescriptor" permalinks="true/false"></div>Disable Swagger validator or define a custom Swagger validator. If parameter not defined, the validator will be 'http://online.swagger.io/validator'
<div swagger-ui url="URLToYourSwaggerDescriptor" validator-url="false or URL"></div>Swagger descriptor parser is chosen depending on the Content-Type of the descriptor response. If host serving your Swagger descriptor does not send Content-Type: application/json then you can force the parser to JSON:
<div swagger-ui url="URLToYourSwaggerDescriptor" parser="json"></div>Add swagger1-to-swagger2-converter.min.js to the end of the body
<body>
...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger1-to-swagger2-converter.min.js"></script>
</body>Add module to angular-swagger-ui
angular
.module('myApp', ['swaggerUi'])
.run(function(swaggerModules, swagger1ToSwagger2Converter){
swaggerModules.add(swaggerModules.BEFORE_PARSE, swagger1ToSwagger2Converter);
})
...See Swagger 2.0 spec Add swagger-external-references.min.js to the end of the body
<body>
...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-external-references.min.js"></script>
</body>Add module to angular-swagger-ui
angular
.module('myApp', ['swaggerUi'])
.run(function(swaggerModules, swaggerUiExternalReferences){
swaggerModules.add(swaggerModules.BEFORE_PARSE, swaggerUiExternalReferences);
})
...Add swagger-xml-formatter.min.js to the end of the body
<body>
...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-xml-formatter.min.js"></script>
</body>Add module to angular-swagger-ui
angular
.module('myApp', ['swaggerUi'])
.run(function(swaggerModules, swaggerUiXmlFormatter){
swaggerModules.add(swaggerModules.AFTER_EXPLORER_LOAD, swaggerUiXmlFormatter);
})
...Modifying 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.
A module is an object (can be a service) having a function execute which must return a promise.
You can make your module modifying behaviours at different phases:
BEFORE_LOAD: allows modifying Swagger descriptor request before it is sentBEFORE_PARSE: allows modifying Swagger descriptor after it has been loadedPARSE: allows adding a Swagger parser for content types other than JSONBEFORE_DISPLAY: allows modifying internal parsed Swagger descriptor before it is displayedBEFORE_EXPLORER_LOAD: allows modifying API explorer request before it is sentAFTER_EXPLORER_LOAD: allows modifying API explorer response before it is displayed
angular
.module('myApp', ['swaggerUi'])
.run(function(swaggerModules, myModule){
swaggerModules.add(swaggerModules.BEFORE_LOAD, myModule);
})
.service('myModule', function($q) {
this.execute = function() {
var deferred = $q.defer();
// if nothing done: call deferred.resolve(false);
// if success: call deferred.resolve(true);
// if error: call deferred.reject({message: 'error message', code: 'error_code'});
return deferred.promise;
}
})
...