当前位置：首页 > 软件库 > Web应用开发 > Web框架 >

angular-swagger-ui

An angularJS implementation of Swagger UI

授权协议 View license

开发语言 JavaScript

所属分类 Web应用开发、 Web框架

软件类型开源软件

地区不详

投递者吕新

操作系统跨平台

开源组织无

适用人群未知

软件概览

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

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

<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="URLToYourOpenAPISpecification" api-explorer="true"></div>

Add swagger-ui.min.js and angular.min.js at 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>

Parameters

API explorer

Display or not API explorer, default is false

<div swagger-ui url="URLToYourOpenAPISpecification" api-explorer="true/false"></div>

OpenAPI specification loading indicator

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

<div ng-show="yourScopeVariable">loading ...</div>
<div swagger-ui url="URLToYourOpenAPISpecification" loading="yourScopeVariable"></div>

Error handler

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

<div swagger-ui url="URLToYourOpenAPISpecification" error-handler="yourErrorHandler"></div>

$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

<div swagger-ui url="URLToYourOpenAPISpecification" permalinks="true/false"></div>

Download

Display or not a link to download swagger file.

<!-- display link with url label -->
<div swagger-ui url="URLToYourOpenAPISpecification" download></div>

<!-- display link with specific key enter in swaggerTranslatorProvider -->
<div swagger-ui url="URLToYourOpenAPISpecification" download="downloadLabel"></div>

OpenAPI validator

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

<div swagger-ui url="URLToYourOpenAPISpecification" validator-url="false or URL"></div>

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:

<div swagger-ui url="URLToYourOpenAPISpecification" parser="json"></div>

Template URL

Define a custom template to be used by OpenAPIUI

<div swagger-ui url="URLToYourOpenAPISpecification" template-url="yourTemplatePath"></div>

Inherited properties

Allows displaying inherited properties of polymorphic models

<div swagger-ui url="URLToYourOpenAPISpecification" show-inherited-properties="true/false"></div>

Input type and input

Render an OpenAPI specification from JSON object

<div swagger-ui input-type="json" input="yourJsonObject"></div>

Render an OpenAPI specification from YAML string

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

<div swagger-ui input-type="yaml" input="yourYamlString"></div>

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

<div swagger-ui input-type="url" input="yourURL"></div>

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

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

Set language to french at startup

<script type="text/javascript">
	angular
		.module('yourApp', ['swaggerUi'])
		.config(function(swaggerTranslatorProvider) {
			swaggerTranslatorProvider.setLanguage('fr');
		});
	...
</script>

Set language to french at runtime

<script type="text/javascript">
	angular
		.module('yourApp', ['swaggerUi'])
		.controller('yourController', function(swaggerTranslator) {
			swaggerTranslator.useLanguage('fr');
		});
	...
</script>

Add languages

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

<script type="text/javascript">
	angular
		.module('yourApp', ['swaggerUi'])
		.config(function(swaggerTranslatorProvider) {
			swaggerTranslatorProvider.addTranslations('yourLangId', {
				key: 'value'
				...
			});
			swaggerTranslatorProvider.setLanguage('yourLangId');
		});
	...
</script>

Internationalize your app

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

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

Customization

Enable OpenAPI 3.0.0

See OpenAPI 3.0.0 spec.Add openapi3-converter.min.js at 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/openapi3-converter.min.js"></script>
</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

<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-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>
</body>

Enable OpenAPI [aka Swagger] 1.2

See OpenAPI 1.2 spec.Add swagger1-converter.min.js at 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-converter.min.js"></script>
</body>

Enable OpenAPI external references

See OpenAPI 2.0 spec.Add swagger-external-references.min.js at 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>

Enable XML formatter on API explorer responses

Add swagger-xml-formatter.min.js at 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>

Enable YAML

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

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

Enable markdown

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

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

使用案例

SpringBoot学习二：整合Swagger UI

现在比较推崇前后端分离的创建项目，前端使用诸如React、Vue、Angular等前端框架，后端使用诸如微服务、Node等；因此，前后端的解耦和至关重要。那后端开发时如何查看开发效果呢？Swagger UI提供了解决方案。下面简单记录一下，SpringBoot整合Swagger UI的方式。加载Swagger的Maven配置文件 <dependency> <groupId>io.spr
swagger-ui 安装配置

Swagger注解-@Api Swagger注解-@ApiOperation Swagger注解-@ApiImplicitParams 和 @ApiImplicitParam Swagger注解-@ApiModel 和 @ApiModelProperty Swagger注解-@ApiResponses 和 @ApiResponse Swagger注解-@ResponseHeader Swagger
Swagger-UI的配置与使用

Swagger-UI 的官方地址： http://swagger.wordnik.com Github上的项目地址： https://github.com/wordnik/swagger-ui 官方提供的demo地址 http://petstore.swagger.wordnik.com/ Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服
Springfox Swagger UI

Swagger介绍及使用相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制
Swagger UI引入

Swagger是一个Restful风格接口的文档在线自动生成和测试的框架（http://swagger.io），Swagger UI可以自动生成接口文档，不需要频繁更新接口文档，保证接口文档与代码的一致，代码改动时，接口文档可以自动修改。 1、添加依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>
Swagger工具组件Swagger-ui的介绍及使用

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。原文地址：Swagger工具组件Swagger-ui的介绍及使用
swagger-ui常用注解

swagger-ui介绍： swagger-ui是一个通过注解自动生成接口文档的技术，这样我们在修改后端接口时，就可以将文档实时同步更新了下面我们来介绍一下常用的注解 @Api (修饰类) 常见参数 value : 类的作用 tags : 非空时会覆盖value的值，可以在ui界面上看到 produces : 设置输出的mime类型，比如 “application/json” consumes
swagger-bootstrap-ui配置

swagger-bootstrap-ui配置 Springboot版本 <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.3.RELEASE</version> <relativeP
SwaggerUI的配置

SwaggerUI的配置使用SwaggerUI比较直观，可以看到参数和返回值的含义，便于测试和联调。在工作上第三次遇到构建SwaggerUI了，把过程记录下。 1，引用 Maven: <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId>
swagger-bootstrap-ui 配置

springboot 配置swagger maven 依赖  <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <vers
下载并安装Swagger-ui和Swagger-edit

下载并安装Swagger-ui和Swagger-edit 1. github上下载好Swagger-ui和Swagger-edit文件 https://github.com/swagger-api/swagger-ui https://github.com/swagger-api/swagger-editor 2. 在本地解压 3. 下载好node以及npm，在cmd中确认下载成功 4.

angular-swagger-ui

angular-swagger-ui

Warning

Demo

Quick Start

Install

Dependencies

License

Getting Started

Parameters

API explorer

OpenAPI specification loading indicator

Error handler

Permalinks

Download

OpenAPI validator

Parser type

Template URL

Inherited properties

Input type and input

Render an OpenAPI specification from JSON object

Render an OpenAPI specification from YAML string

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

i18n

Built-in languages

Add languages

Internationalize your app

Customization

Enable OpenAPI 3.0.0

Enable authorization

Enable OpenAPI [aka Swagger] 1.2

Enable OpenAPI external references

Enable XML formatter on API explorer responses

Enable YAML

Enable markdown

Writing your own modules

同类工具

相关阅读

相关文章

相关问答

相关文档