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 moduleswagger1-converter
see Enable OpenAPI 1.2. To handle authorization please add moduleswagger-auth
see Enable authorization To handle YAML please add moduleswagger-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
- angularJS
- bootstrap CSS
- 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 (seedist/index.html
as an example) - You CAN add
trusted-sources="true"
as directive parameter (avoids embeddingngSanitize
) if OpenAPI specifications are loaded from trusted sources (seesrc/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
... <!-- if you choosed to use "ngSanitize" -->
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
loading ...
Error handler
Define an error handler to catch errors, if none defined console.error
is used
$scope{ }
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.
<!-- display link with url label --> <!-- display link with specific key enter in swaggerTranslatorProvider -->
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
...<!-- without angular-ui-bootstrap modal embedded --> OR<!-- angular-ui-bootstrap modal embedded --> ...
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 sentBEFORE_PARSE
: allows modifying OpenAPI specification after it has been loadedPARSE
: allows adding an OpenAPI parser for content types other than JSONBEFORE_DISPLAY
: allows modifying internal parsed OpenAPI specification 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 ...