angular-swagger-ui, angularJS实现Swagger用户界面

分享于 

17分钟阅读

GitHub

  繁體
An angularJS implementation of Swagger UI
  • 源代码名称:angular-swagger-ui
  • 源代码网址:http://www.github.com/Orange-OpenSource/angular-swagger-ui
  • angular-swagger-ui源代码文档
  • angular-swagger-ui源代码下载
  • Git URL:
    git://www.github.com/Orange-OpenSource/angular-swagger-ui.git
    Git Clone代码到本地:
    git clone http://www.github.com/Orange-OpenSource/angular-swagger-ui
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/Orange-OpenSource/angular-swagger-ui
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    angular-swagger-ui

    angular-swagger-ui是OpenAPI UI的angularJS实现

    警告

    默认情况下,仅支持OpenAPI 2.0,要处理OpenAPI 3.0.0,请添加模块openapi3-converter请参见演示

    可以使用angular-swagger-ui的样例应用程序:

    快速入门

    安装

    npm install angular-swagger-ui

    依赖性

    许可证

    此存储库中的所有代码都由入门

    angular-swagger-ui作为依赖项包含在应用程序中

    由于OpenAPI规范的某些属性可以格式化为HTML:

    如果从不受信任的源加载规范,则应将ngSanitize作为依赖项包含在应用程序(避免JS注入)中(请参见的示例),如果trusted-sources="true"规范是从信任源加载的,则可以添加作为指令参数(避免嵌入ngSanitize )(请参见OpenAPI作为示例),必须至少选择前两个解决方案中的一个
    <scripttype="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>

    在angularJS应用程序的模板或HTML页面中创建一个HTML元素

    <divswagger-uiurl="URLToYourOpenAPISpecification"api-explorer="true"></div>

    在正文末尾添加swagger-ui.min.jsangular.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <!-- if you choosed to use"ngSanitize" --> <scriptsrc="yourPathToAngularSanitize/angular-sanitize.min.js"></script>
    </body>

    swagger-ui.min.cssbootstrap.min.css添加到HTML页面的头部。

    <body>
     <head>
     ...
     <linkrel="stylesheet"href="yourPathToBootstrapCSS/bootstrap.min.css">
     <linkrel="stylesheet"href="yourPathToAngularSwaggerUI/dist/css/swagger-ui.min.css">
     </head>
    </body>

    参数

    API资源管理器

    显示或不显示API explorer默认为false

    <divswagger-uiurl="URLToYourOpenAPISpecification"api-explorer="true/false"></div>
    OpenAPI规范加载指示器

    yourScopeVariable将根据false规范加载状态分配给true或OpenAPI

    <divng-show="yourScopeVariable">loading ...</div>
    <divswagger-uiurl="URLToYourOpenAPISpecification"loading="yourScopeVariable"></div>
    错误处理程序

    定义一个错误处理程序来捕获错误,如果未使用定义的console.error

    <divswagger-uiurl="URLToYourOpenAPISpecification"error-handler="yourErrorHandler"></div>
    $scope.yourErrorHandler=function(/*String or Object*/message, /*Integer*/code){
    }
    永久链接

    允许URL直接访问一组操作或操作,并在启动时将它展开,

    <divswagger-uiurl="URLToYourOpenAPISpecification"permalinks="true/false"></div>
    下载

    显示或不显示下载swagger文件的链接。

    <!-- display link with url label --><divswagger-uiurl="URLToYourOpenAPISpecification"download></div><!-- display link with specific key enter in swaggerTranslatorProvider --><divswagger-uiurl="URLToYourOpenAPISpecification"download="downloadLabel"></div>
    OpenAPI验证器

    禁用OpenAPI验证器或定义自定义OpenAPI验证器,如果参数未定义,验证器将为{ http://online.swagger.io/validator}',

    <divswagger-uiurl="URLToYourOpenAPISpecification"validator-url="false or URL"></div>
    分析器类型

    选择OpenAPI规范解析器取决于规范响应的Content-Type,如果为OpenAPI规范提供的主机不发送Content-Type: application/json,那么你可以强制解析器到JSON:

    <divswagger-uiurl="URLToYourOpenAPISpecification"parser="json"></div>
    模板URL

    定义OpenAPIUI要使用的自定义模板

    <divswagger-uiurl="URLToYourOpenAPISpecification"template-url="yourTemplatePath"></div>
    输入类型和输入从JSON对象呈现OpenAPI规范
    <divswagger-uiinput-type="json"input="yourJsonObject"></div>
    呈现来自YAML字符串的OpenAPI规范

    确保使用模块swagger-yaml-parser请参见启用YAML

    <divswagger-uiinput-type="yaml"input="yourYamlString"></div>
    从URL (使用相同的行为"URL"参数呈现OpenAPI规范)
    <divswagger-uiinput-type="url"input="yourURL"></div>

    i18n

    内置语言

    angular-swagger-ui在英语和法语中可用,默认使用英语,

    要使用french,请在正文末尾添加fr.min.js

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

    启动时将语言设置为法语

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

    在运行时将语言设置为法语

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

    你可以添加自己的语言,请参见src/scripts/i18n/en.js来查找必须重写的键,

    <scripttype="text/javascript"> angular .module('yourApp', ['swaggerUi']) .config(function(swaggerTranslatorProvider) {swaggerTranslatorProvider.addTranslations('yourLangId', { key:'value'... });swaggerTranslatorProvider.setLanguage('yourLangId'); });...</script>
    国际化你的应用程序

    你还可以使用swaggerTranslator使用服务,指令或过滤器来国际化你的应用程序,

    <body>
     ...
     <divswagger-translate="yourKey"swagger-translate-value="yourParam"></div>
     <divng-bind="yourDynamicKey|swaggerTranslate:yourDynamicParam"></div>
     ...
     <scripttype="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>

    自定义

    启用OpenAPI 3.0.0

    请参见openAPI 3.0.0规范。在正文末尾添加openapi3-converter.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/openapi3-converter.min.js"></script>
    </body>
    启用授权

    未实现oauth,仅实现basicAPI key授权。在正文末尾添加swagger-auth.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth.min.js"></script><!-- without angular-ui-bootstrap modal embedded --> OR
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-auth-ui-boostrap-modal.min.js"></script><!-- angular-ui-bootstrap modal embedded --> ...
     <scripttype="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.credentials({// optional apiKey: { yourApiKeyName:'yourApiKeyValue'// optional, can be used to initialize api key value },// optional basic: { login:'yourLogin', // optional, can be used to initialize basic login password:'yourPassword'// optional, can be used to initialize basic password },// what is below is required for oauth2 flows 'implicit' and 'accessCode' (ie. authorizationCode) oauth2: { 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 or basic credentials password:'yourPassword', // optional, can be used to initialize oauth2 or basic credentials apiKey:'yourApiKey', // optional, can be used to initialize API key credentials redirectUrl:'yourPathToAngularSwaggerUI/oauth2-redirect.html'// required for oauth2 flow 'implicit' and 'accessCode' (ie. authorizationCode) }, }); })...</script>
    </body>
    启用OpenAPI [aka Swagger] 1.2

    请参见OpenAPI 1.2规范。在正文末尾添加swagger1-converter.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger1-converter.min.js"></script>
    </body>
    启用OpenAPI外部引用

    请参见OpenAPI 2.0规范。在正文末尾添加swagger-external-references.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-external-references.min.js"></script>
    </body>
    在API explorer响应上启用XML格式化程序

    在正文末尾添加swagger-xml-formatter.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-xml-formatter.min.js"></script>
    </body>
    启用YAML

    添加js yaml库。在正文末尾添加swagger-yaml-parser.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToJsYaml/js-yaml.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-yaml-parser.min.js"></script>
    </body>
    启用Markdown

    添加标记库。在正文末尾添加swagger-markdown.min.js

    <body>
     ...
     <scriptsrc="yourPathToAngularJS/angular.min.js"></script>
     <scriptsrc="yourPathToMarked/marked.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/swagger-ui.min.js"></script>
     <scriptsrc="yourPathToAngularSwaggerUI/dist/scripts/modules/swagger-markdown.min.js"></script>
    </body>
    编写你自己的模块

    通过编写你自己的模块,可以修改angular-swagger-ui,作为一个例子,你可以查看src/scripts/modules中的那些,模块是具有函数(可以是服务)的对象execute必须返回promise。

    你可以让你的模块在不同的阶段修改行为:

    BEFORE_LOAD:允许在发送OpenAPI规范请求之前修改它BEFORE_PARSE:允许在加载OpenAPI规范之后修改它PARSE:允许为JSON以外的内容类型添加OpenAPI解析器BEFORE_DISPLAY:允许在显示之前修改内部解析的OpenAPI规范BEFORE_EXPLORER_LOAD:允许在发送API explorer请求之前修改它AFTER_EXPLORER_LOAD:允许在显示API explorer响应之前修改它
    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'});returndeferred.promise;
     }
     })
     .run(function(swaggerModules, myModule){
     // default priority is 1// higher is the priority, sooner the module is executed at the specified phaseswaggerModules.add(swaggerModules.BEFORE_LOAD, myModule, priority);
     })
     ...

    相关文章