Spring Boot + Swagger + 自定义 swagger-ui.html

Posted 2023-02-26

技术标签:

【中文标题】Spring Boot + Swagger + 自定义 swagger-ui.html【英文标题】：Spring Boot + Swagger + custom swagger-ui.html 【发布时间】：2017-02-19 22:38:10 【问题描述】：

我在将 war 应用程序迁移到 spring boot jar 应用程序时遇到问题。

我正在使用 spring boot 1.4.1 和 swagger 2.6.0。

要在战争中自定义 swagger ui，您必须将自定义 swagger-ui.html 放入 /webapp 目录。在 Spring Boot 中，不建议使用 webapp 目录，因为它在捆绑的 jar 中不起作用。但是将自定义的 swagger-ui.html 放入 /resources/static 会被 swagger 忽略。

是否有任何简单的解决方案（而不是将整个 swagger 分发添加到我的应用程序）？

我的自定义 swagger-ui.html 看起来像

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

<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

<style>
    .swagger-section #header 
        background-color: #ff5722;
    
</style>
</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://www.my-app.com">my-app.com API</a>

        <form id='api_selector'>
            <div class='input' style="display: none">
                <select id="select_baseUrl" name="select_baseUrl"/>
            </div>
            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl"
                                  type="text"/>
            </div>
            <!--
            <div class='input'><input placeholder="Enter authorization token" id="input_apiKey" name="apiKey" type="text"/></div>
            <div class='input' style="display: none"><a id="explore" href="#" data-sw-translate>Explore</a></div>
            -->
        </form>
    </div>
</div>

<script type="text/javascript">
    function addApiKeyAuthorization() 
        var key = $('#input_apiKey')[0].value;
        console.log("key: " + key);
        if (key && key.trim() != "") 
            var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("Authorization", key, "header");
            window.swaggerUi.api.clientAuthorizations.add("bearer", apiKeyAuth);
            //window.authorizations.add("Authorization", new ApiKeyAuthorization("Authorization", key, "query"));
        console.log("Set authorization token: " + key);
        
    
    $('#input_apiKey').change(function () 
        addApiKeyAuthorization();
    );
</script>

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

【问题讨论】：

您可以构建一个war文件，该文件既可以像jar文件一样执行，也可以部署到外部容器中并继续使用webapp目录。非常感谢，但我不想发布战争（仅支持 webapp 文件夹）。到目前为止，唯一的方法似乎是从 github.com/swagger-api/swagger-ui/tree/master/dist 添加整个 ui 分发并对其进行自定义。为什么不直接 fork/copy springfox-swagger-ui？它已经是一个预打包的 webjar。我希望有一种简单的方法，比如将 swagger-ui.html 放到 webapp 根文件夹中。 【参考方案1】：

我发现这种简单的方法可以将 Swagger 自定义到 Spring Boot 应用程序中，只需从原始 springfox-swagger-ui 复制两个文件

首先我从 SwaggerConfig.java 中禁用了@Configuration：

//@Configuration <-- Attention, disable Configuration
@EnableSwagger2
public class SwaggerConfig 

    @Bean
    public Docket productApi() 
        return new Docket(DocumentationType.SWAGGER_2)
                .ignoredParameterTypes(Pageable.class)
                .select().apis(RequestHandlerSelectors.any())
                .paths(regex("/v1/.*"))
                .build();

然后我扩展了一个WebMvcConfigurerAdapter：

@Configuration
@Import(SwaggerConfig.class)
public class MvcConfig extends WebMvcConfigurerAdapter 
    @Override
    public void addResourceHandlers(final ResourceHandlerRegistry registry) 
        registry.addResourceHandler("/doc/v1/**").addResourceLocations("classpath:/doc/v1/");
        registry.addResourceHandler("/doc/v1/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

然后我刚刚将原始文件 swagger-ui.html 复制到 src/main/resources/doc/v1/api.html 中，并进行了简单的修改。我已经替换了这一行：

<script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

用这一行：

<script src='js/swagger.js' type='text/javascript'></script>

这是我的 api.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

    <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>

    <script src='js/springfox.js' type='text/javascript'></script>
</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io"><img class="logo__img"    src="webjars/springfox-swagger-ui/images/logo_small.png" /><span class="logo__title">swagger</span></a>
        <form id='api_selector'>
            <div class='input'>
                <select id="select_baseUrl" name="select_baseUrl"/>
            </div>
            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
            <div id='auth_container'></div>
            <div class='input'><a id="explore" class="header__btn" 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>

之后，我将原始 springfox.js 复制到 src/main/resources/doc/v1/js/springfox.js 中，并在其中更改了这些行：

"baseUrl": function() 
      var urlMatches = /(.*)\/swagger-ui.html.*/.exec(window.location.href);
      return urlMatches[1];
    ,

这些行：

"baseUrl": function() 
            return window.location.origin;
        ,

这是我完整的 springfox.js

$(function() 
    var springfox = 
        "baseUrl": function() 
            return window.location.origin;
        ,
        "securityConfig": function(cb) 
            $.getJSON(this.baseUrl() + "/swagger-resources/configuration/security", function(data) 
                cb(data);
            );
        ,
        "uiConfig": function(cb) 
            $.getJSON(this.baseUrl() + "/swagger-resources/configuration/ui", function(data) 
                cb(data);
            );
        
    ;
    window.springfox = springfox;
    window.oAuthRedirectUrl = springfox.baseUrl() + '/webjars/springfox-swagger-ui/o2c.html';

    window.springfox.uiConfig(function(data) 
        window.swaggerUi = new SwaggerUi(
            dom_id: "swagger-ui-container",
            validatorUrl: data.validatorUrl,
            supportedSubmitMethods: data.supportedSubmitMethods || ['get', 'post', 'put', 'delete', 'patch'],
            docExpansion: data.docExpansion || 'none',
            jsonEditor: JSON.parse(data.jsonEditor) || false,
            apisSorter: data.apisSorter || 'alpha',
            defaultModelRendering: data.defaultModelRendering || 'schema',
            showRequestHeaders: data.showRequestHeaders || true,
            timeout: data.requestTimeout,
            onComplete: function(swaggerApi, swaggerUi) 

                initializeSpringfox();

                if (window.SwaggerTranslator) 
                    window.SwaggerTranslator.translate();
                

                $('pre code').each(function(i, e) 
                    hljs.highlightBlock(e)
                );

            ,
            onFailure: function(data) 
                log("Unable to Load SwaggerUI");
            ,
        );

        initializeBaseUrl();

        function addApiKeyAuthorization(security) 
            var apiKeyVehicle = security.apiKeyVehicle || 'query';
            var apiKeyName = security.apiKeyName || 'api_key';
            var apiKey = security.apiKey || '';
            if (apiKey && apiKey.trim() != "") 
                var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization(apiKeyName, apiKey, apiKeyVehicle);
                window.swaggerUi.api.clientAuthorizations.add(apiKeyName, apiKeyAuth);
                log("added key " + apiKey);
            
        

        function log() 
            if ('console' in window) 
                console.log.apply(console, arguments);
            
        

        function oAuthIsDefined(security) 
            return security.clientId
                && security.clientSecret
                && security.appName
                && security.realm;
        

        function initializeSpringfox() 
            var security = ;
            window.springfox.securityConfig(function(data) 
                security = data;
                addApiKeyAuthorization(security);
                if (typeof initOAuth == "function" && oAuthIsDefined(security)) 
                    initOAuth(security);
                
            );
        
    );

    $('#select_baseUrl').change(function() 
        window.swaggerUi.headerView.trigger('update-swagger-ui', 
            url: $('#select_baseUrl').val()
        );
    );

    function maybePrefix(location, withRelativePath) 
        var pat = /^https?:\/\//i;
        if (pat.test(location)) 
            return location;
        
        return withRelativePath + location;
    

    function initializeBaseUrl() 
        var relativeLocation = springfox.baseUrl();

        $('#input_baseUrl').hide();

        $.getJSON(relativeLocation + "/swagger-resources", function(data) 

            var $urlDropdown = $('#select_baseUrl');
            $urlDropdown.empty();
            $.each(data, function(i, resource) 
                var option = $('<option></option>')
                    .attr("value", maybePrefix(resource.location, relativeLocation))
                    .text(resource.name + " (" + resource.location + ")");
                $urlDropdown.append(option);
            );
            $urlDropdown.change();
        );

    

);

This is my folder structure

现在您只需运行应用程序并转到http://localhost:8080/doc/v1/api.html

【讨论】：

【参考方案2】：

如果您使用的是 maven 解决方案：

你应该将swagger-ui.html复制到src/main/webapp

制作您的版本或将 screen.css 替换为您的 theme.css

将这些代码添加到您的pom.xml：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <configuration>
                <webResources>
                    <resource>
                        <directory>$basedir/src/main/webapp</directory>
                        <filtering>true</filtering>
                        <includes>
                            <include>*.css</include>
                            <include>*.html</include>
                        </includes>
                    </resource>
                </webResources>
            </configuration>
        </plugin>
    </plugins>
</build>

【讨论】：

spring boot - 创建 jars 而不是战争你也可以用 Spring boot 来制造战争正确。如果你（在你的 pom.xml 中）打包成一个战争，spring boot 会生成一个 WAR 文件

以上是关于Spring Boot + Swagger + 自定义 swagger-ui.html的主要内容，如果未能解决你的问题，请参考以下文章

spring boot整合swagger时，打开swagger-ui中文出现乱码

Spring Boot 集成 Swagger，再也不写接口文档了！

Spring boot 参数校验

Swagger Learing - Spring Boot 整合swagger

Spring Boot 集成Swagger