swagger-ui 响应示例作为定义中的参考

Question

有没有办法在 'definitions' 中定义响应示例对象并使用“$ref”引用它：“#/definitions/ResponseExample”？

这是我目前的回复：

"200": {
    "description" :"Successful operation",
    "schema" : {
        "$ref" : "#/definitions/AttributesBasicResponse"
    },
    "examples": {
        "application/json": {
            "data": [
                {
                    "name" :"My data",
                    "code": "DATA",
                    "units": "UK, US, EU"
                }
            ],
            "attribute": "test"
        }
    }
}

我想要实现的是：

"200": {
    "description" :"Successful operation",
    "schema" : {
        "$ref" : "#/definitions/AttributesBasicResponse"
    },
    "examples": {
        "$ref": "#/definitions/AttributeBasicExample"
    }
}

Answer 1

我决定在将 json 对象传递到 swaggerUI 之前使用 whitlockjc/json-refs 解析 JSON 引用。

在这种情况下，使用 jQuery.get、运行 JsonRefs.resolveRefs 加载 swagger.json 来解析 'relative' 引用，然后将已解析的 json 传递给 swaggerUi.setOption('spec', json) 并更新 swaggerUi.load()

这是在浏览器端完成的，我可以在服务器端使用 nodejs 来减少 http 请求的数量。

已更新 swagger-ui index.html:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
    <link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
    <link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
    <link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
    <script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
    <script src='lib/underscore-min.js' type='text/javascript'></script>
    <script src='lib/backbone-min.js' type='text/javascript'></script>
    <script src='swagger-ui.js' type='text/javascript'></script>
    <script src='lib/highlight.7.3.pack.js' type='text/javascript'></script>
    <script src='lib/jsoneditor.min.js' type='text/javascript'></script>
    <script src='lib/marked.js' type='text/javascript'></script>
    <script src='lib/swagger-oauth.js' type='text/javascript'></script>

    <script src='lib/json-refs-standalone.js' type='text/javascript'></script>

    <script type="text/javascript">
        $(function () {
            var url = window.location.search.match(/url=([^&]+)/);
            if (url && url.length > 1) {
                url = decodeURIComponent(url[1]);
            } else {
                url = "http://petstore.swagger.io/v2/swagger.json";
            }
            // Pre load translate...
            if(window.SwaggerTranslator) {
                window.SwaggerTranslator.translate();
            }
            window.swaggerUi = new SwaggerUi({
                url: url,
                dom_id: "swagger-ui-container",
                supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
                onComplete: function(swaggerApi, swaggerUi){
                    if(typeof initOAuth == "function") {
                        initOAuth({
                            clientId: "your-client-id",
                            clientSecret: "your-client-secret-if-required",
                            realm: "your-realms",
                            appName: "your-app-name",
                            scopeSeparator: ",",
                            additionalQueryStringParams: {}
                        });
                    }
                    if(window.SwaggerTranslator) {
                        window.SwaggerTranslator.translate();
                    }
                    $('pre code').each(function(i, e) {
                        hljs.highlightBlock(e)
                    });
                    addApiKeyAuthorization();
                },
                onFailure: function(data) {
                    log("Unable to Load SwaggerUI");
                },
                docExpansion: "none",
                jsonEditor: false,
                apisSorter: "alpha",
                defaultModelRendering: 'schema',
                showRequestHeaders: false
            });

            function changedBaseUrl( event ) {
                event.preventDefault();

                var url = $(this ).val();

                $.get( url ,function(response){
                    // do the json-refs first
                    JsonRefs.resolveRefs( response, { relativeBase: '/swagger',filter: [ 'relative' ] } )
                        .then(function( response ){
                            var json = response.resolved;

                            window.swaggerUi.setOption('spec', json);
                            window.swaggerUi.load();

                            // resolve failed
                        }, function( error ){
                            console.log("failure", error);
                        });
                });
            }

            function addApiKeyAuthorization(){
                var key = encodeURIComponent($('#input_apiKey')[0].value);
                if(key && key.trim() != "") {
                    var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("api_key", key, "query");
                    window.swaggerUi.api.clientAuthorizations.add("api_key", apiKeyAuth);
                    log("added key " + key);
                }
            }
            $('#input_baseUrl').change(changedBaseUrl);
            $('#input_apiKey').change(addApiKeyAuthorization);
            // if you have an apiKey you would like to pre-populate on the page for demonstration purposes...
            /*
             var apiKey = "myApiKeyXXXX123456789";
             $('#input_apiKey').val(apiKey);
             */

            window.swaggerUi.load();

            function log() {
                if ('console' in window) {
                    console.log.apply(console, arguments);
                }
            }
        });
    </script>
</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io">swagger</a>
        <form id='api_selector'>
            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
            <div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
            <div class='input'><a id="explore" href="#" data-sw-translate>Explore</a></div>
        </form>
    </div>
</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate>&nbsp;</div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>

样本swagger.json:

{
    "swagger": "2.0",
    "info": {
        "title": "Basic Login",
        "version": " 1.0.0"
    },
    "paths": {
        "login": {
            "post": {
                "summary": "User login",
                "tags" : [ "Login" ],
                "responses" : {
                    "200": {
                        "description" :"Returns authorization hash",
                        "schema" : {
                            "$ref" : "./schemas/login.json"
                        },
                        "examples": {
                            "$ref": "./responses/login/login.json"
                        }
                    }
                }
            }
        }
    }
}

架构login.json

{
    "type" : "object",
    "properties": {
        "data": {
            "type": "object",
            "properties": {
                "auth_hash": {
                    "type": "string"
                }
            }
        }
    }
}

示例login.json:

{
    "data": {
        "auth_hash": "e2ad8410efa2d68cedad76b83eb97ecd"
    }
}

JsonRefs 具有运行后的最终结果：

{
    "swagger": "2.0",
    "info": {
        "title": "Basic Login",
        "version": " 1.0.0"
    },
    "paths": {
        "login": {
            "post": {
                "summary": "User login",
                "tags": [
                    "Login"
                ],
                "responses": {
                    "200": {
                        "description": "Returns authorization hash",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "data": {
                                    "type": "object",
                                    "properties": {
                                        "auth_hash": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        },
                        "examples": {
                            "data": {
                                "auth_hash": "e2ad8410efa2d68cedad76b83eb97ecd"
                            }
                        }
                    }
                }
            }
        }
    }
}

使用的其他参考资料：

swagger-ui 响应示例作为定义中的参考

swagger-ui response example as reference in definitions

javascript

json

swagger-ui

swagger-2.0