angular-swagger-ui

by Orange-OpenSource

Orange-OpenSource /angular-swagger-ui

An angularJS implementation of Swagger UI

132 Stars 73 Forks Last release: 3 months ago (0.6.4) Other 343 Commits 37 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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 authorization To 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

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

...
<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>

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

html


        ...
        
        


Parameters

API explorer

Display or not API explorer, default is

false
html

OpenAPI specification loading indicator

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

Error handler

Define an error handler to catch errors, if none defined

console.error
is used
html
```js $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

html

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'

html

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

Template URL

Define a custom template to be used by OpenAPIUI

html

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
html
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
html

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/i18/fr.min.js"></script>

Set language to french at startup

html

Set language to french at runtime

html

Add languages

You can add your own languages, see

src/scripts/i18n/en.js
to find the keys you have to override
html

Internationalize your app

You can also use

swaggerTranslator
to internationalize your app by using a service, a directive or a filter
html

...
<div swagger-translate="yourKey" swagger-translate-value="yourParam"></div>
<div ng-bind="yourDynamicKey|swaggerTranslate:yourDynamicParam"></div>
...
<script type="text/javascript">
    angular
        .module('yourApp', ['swaggerUi'])
        .config(function(swaggerTranslatorProvider) {
            swaggerTranslatorProvider.addTranslations('en', {
                yourKey: 'blablabla {{propertyNameOfYourParam}}'
                ...
            });
        })
        .controller('yourController', function(swaggerTranslator) {
            var localizedMessage = swaggerTranslator.translate('yourKey', yourParam);
        });
    ...
</script>

Customization

Enable OpenAPI 3.0.0

See OpenAPI 3.0.0 spec. Add

openapi3-converter.min.js
at the end of the body
html

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/openapi3-converter.min.js"></script>

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
html

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth.min.js"></script><!-- without angular-ui-bootstrap modal embedded -->
OR
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth-ui-boostrap-modal.min.js"></script><!-- angular-ui-bootstrap modal embedded -->
...
<script type="text/javascript">
    angular
        .module('yourApp', ['swaggerUi', 'swaggerUiAuthorization'])
        // what is below is required for oauth2 flows 'implicit' and 'accessCode' (ie. authorizationCode)
        // what is below can also be used to initialize apiKey or Basic authorizations
  .config(function(swaggerUiAuthProvider) {
      swaggerUiAuthProvider.configuration({
          // required for oauth2 flow 'implicit' and 'accessCode' (ie. authorizationCode)
            redirectUrl: 'yourPathToAngularSwaggerUI/oauth2-redirect.html' 
          // optional
          yourSecurityName: {
            apiKey: 'yourApiKeyValue' // optional, can be used to initialize api key value
          },
          // optional
          yourSecurityName: {
            login: 'yourLogin', // optional, can be used to initialize basic login
            password: 'yourPassword' // optional, can be used to initialize basic password
          },
          // optional
          yourSecurityName: {
            clientId: 'yourClientId', // optional, can be used to initialize oauth2 credentials
            clientSecret: 'yourClientSecret', // optional, can be used to initialize oauth2 credentials
            login: 'yourLogin', // optional, can be used to initialize oauth2 credentials
            password: 'yourPassword', // optional, can be used to initialize oauth2 credentials
            scopeSeparator: 'scopeSeparator', // optional, can be used to configure oauth2 scopes separator, default value is space
            // optional, can be used to configure oauth2 additional query params to tokenUrl and authorizationUrl
            queryParams: {
                'yourQueryParamName': 'yourQueryParamValue'
                ...
            }, 
          },
      });
  })
        ...
</script>

Enable OpenAPI [aka Swagger] 1.2

See OpenAPI 1.2 spec. Add

swagger1-converter.min.js
at the end of the body
html

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger1-converter.min.js"></script>

Enable OpenAPI external references

See OpenAPI 2.0 spec. Add

swagger-external-references.min.js
at the end of the body
html

...
<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>

Enable XML formatter on API explorer responses

Add

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

...
<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>

Enable YAML

Add js-yaml library. Add

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

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToJsYaml/js-yaml.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-yaml-parser.min.js"></script>

Enable markdown

Add marked library. Add

swagger-markdown.min.js
at the end of the body
html

...
<script src="yourPathToAngularJS/angular.min.js"></script>
<script src="yourPathToMarked/marked.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
<script src="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-markdown.min.js"></script>

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);
})
...

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.