GitHub - Orange-OpenSource/angular-swagger-ui: An angularJS implementation of Swagger UI (original) (raw)

angular-swagger-ui

angular-swagger-ui is an angularJS implementation of OpenAPI UI

OpenAPI (aka Swagger) helps you documenting your RESTful API.

OpenAPI UI helps developers discovering your RESTful API by providing an online documentation with an integrated API explorer.

Warning

By default, only OpenAPI 2.0 is supported. To handle OpenAPI 3.0.0 please add module openapi3-converter see Enable OpenAPI 3.0.0. To handle OpenAPI 1.2 please add module swagger1-converter see Enable OpenAPI 1.2. To handle authorization please add module swagger-auth see Enable authorizationTo handle YAML please add module swagger-yaml-parser see Enable YAML

Demo

A sample app using angular-swagger-ui is available here:

http://orange-opensource.github.io/angular-swagger-ui

Quick Start

Install

npm install angular-swagger-ui

Dependencies

1. angularJS
2. bootstrap CSS
3. angular-ui-bootstrap (required only if using Authorization)

License

All code in this repository is covered by the MIT license. See LICENSE file for copyright details.

Getting Started

Include angular-swagger-ui as a dependency into your application

As some properties of OpenAPI specifications can be formatted as HTML:

• 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)
• 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)
• You MUST at least choose one of the two previous solutions

Create an HTML element in your angularJS application's template or in your HTML page

Add swagger-ui.min.js and angular.min.js at the end of the body

Add swagger-ui.min.css and bootstrap.min.css to the head of the HTML page.

Parameters

API explorer

Display or not API explorer, default is false

OpenAPI specification loading indicator

yourScopeVariable will be assigned to true or false depending on OpenAPI specification loading status

Error handler

Define an error handler to catch errors, if none defined console.error is used

$scope.yourErrorHandler = function(/String or Object/ message, /Integer/ code){

}

Permalinks

Allows having a URL direct access to a group of operations or to an operation and making it unfolded at startup

Download

Display or not a link to download swagger file.

OpenAPI validator

Disable OpenAPI validator or define a custom OpenAPI validator. If parameter not defined, the validator will be 'http://online.swagger.io/validator'

Parser type

OpenAPI 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:

Template URL

Define a custom template to be used by OpenAPIUI

Inherited properties

Allows displaying inherited properties of polymorphic models

Input type and input

Render an OpenAPI specification from JSON object

Render an OpenAPI specification from YAML string

Make sure to use module swagger-yaml-parser, see Enable YAML

Render an OpenAPI specification from URL (same behavior as using "url" parameter)

i18n

Built-in languages

angular-swagger-ui is available in english and french, english is used by default

To use french, add fr.min.js at the end of the body

Set language to french at startup

Set language to french at runtime

Add languages

You can add your own languages, see src/scripts/i18n/en.js to find the keys you have to override

Internationalize your app

You can also use swaggerTranslator to internationalize your app by using a service, a directive or a filter

Customization

Enable OpenAPI 3.0.0

See OpenAPI 3.0.0 spec. Add openapi3-converter.min.js at the end of the body

Enable authorization

oauth is not implemented, only basic and API key authorizations are implemented. Add swagger-auth.min.js at the end of the body

Enable OpenAPI [aka Swagger] 1.2

See OpenAPI 1.2 spec. Add swagger1-converter.min.js at the end of the body

Enable OpenAPI external references

See OpenAPI 2.0 spec. Add swagger-external-references.min.js at the end of the body

Enable XML formatter on API explorer responses

Add swagger-xml-formatter.min.js at the end of the body

Enable YAML

Add js-yaml library. Add swagger-yaml-parser.min.js at the end of the body

Enable markdown

Add marked library. Add swagger-markdown.min.js at the end of the body

Writing your own modules

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 OpenAPI specification request before it is sent
• BEFORE_PARSE: allows modifying OpenAPI specification after it has been loaded
• PARSE: allows adding an OpenAPI parser for content types other than JSON
• BEFORE_DISPLAY: allows modifying internal parsed OpenAPI specification before it is displayed
• BEFORE_EXPLORER_LOAD: allows modifying API explorer request before it is sent
• AFTER_EXPLORER_LOAD: allows modifying API explorer response before it is displayed

angular .module('myApp', ['swaggerUi']) .service('myModule', function($q) {

    this.execute = function(data) {
        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;
    }

})
.run(function(swaggerModules, myModule){
    // default priority is 1
    // higher is the priority, sooner the module is executed at the specified phase
    swaggerModules.add(swaggerModules.BEFORE_LOAD, myModule, priority);
})
...