Swagger V3 Java 整合记录

最最重要的前言

以下文章是针对 swagger v3 版本的 整合过程 ,这里用了 jersey  , 整个过程其实很简单 , 但是社区里面没有找到中意的过程 , 一会弄完的事情却花了大半天 ,属实不太划算 .

所以 , 这是整个源码 ,拿去不谢 , 下面其实不用看了 , 感觉省事了麻烦点个赞
https://github.com/black-ant/case/tree/master/case%201.5.1%20swaggerv3

Swagger 简述

> openAPI : Rest API 的 API 描述格式 ，包括 端点 ，操作 ，输入输出 ，许可等

> swagger : 用于设计使用 OpenAPI
 

Swagger 完整记录

> Swagger 支持多种Rest 框架 , 以下流程是基于 Jersey + SpringBoot 的整合文档
// 真正和 Swagger 进行整合的不是 spring ,也不是Jersey 或者 restEasy 等框架 , swagger 是基于 javax.ws.rs 包下注解的扫描
    

step1 : Maven 依赖

// 这里只列举几个核心
   <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger-core.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.datatype</groupId>
                    <artifactId>jackson-dataformat-yaml</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2-servlet-initializer</artifactId>
            <version>${swagger-core.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-jaxrs2</artifactId>
            <version>${swagger-core.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>${swagger-core.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.datatype</groupId>
                    <artifactId>jackson-dataformat-yaml</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>swagger-ui</artifactId>
            <version>${swagger-ui.version}</version>
        </dependency>

<!--不要忘了 plugin -->
<plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <inherited>true</inherited>
                <executions>
                    <execution>
                        <id>copy-swagger-resources-in-place</id>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${project.build.directory}/classes/META-INF/resources/swagger
                            </outputDirectory>
                            <resources>
                                <resource>
                                    <directory>
                                        ${project.build.directory}/swagger-ui/META-INF/resources/webjars/swagger-ui/${swagger-ui.version}
                                    </directory>
                                    <excludes>
                                        <exclude>index.html</exclude>
                                    </excludes>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <inherited>true</inherited>
                <executions>
                    <execution>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>unpack</goal>
                        </goals>
                        <configuration>
                            <artifactItems>
                                <artifactItem>
                                    <groupId>org.webjars</groupId>
                                    <artifactId>swagger-ui</artifactId>
                                    <version>${swagger-ui.version}</version>
                                    <overWrite>true</overWrite>
                                    <outputDirectory>${project.build.directory}/swagger-ui</outputDirectory>
                                    <excludes>**/*.gz</excludes>
                                </artifactItem>
                            </artifactItems>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

step 2 : openapi.yml : 核心配置文件

resourcePackages:
  - com.gang.study.swaggerv3.demo.controller
prettyPrint: true
cacheTTL: 0
openAPI:
  info:
    version: '1.0'
    title: Swagger Pet Sample App Config File
    description: 'This is a sample server Petstore server.  You can find out more
      about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net,
      #swagger](http://swagger.io/irc/).  For this sample, you can use the api key
      `special-key` to test the authorization filters.'
    termsOfService: http://swagger.io/terms/
    contact:
      email: apiteam@swagger.io
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html

step 4 : 主界面 index.html

放在 Resource / META-INF/resources/swagger下 ,手动创建的文件夹

<!DOCTYPE html>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->
<html lang="en">
<head>
    <meta charset="UTF-8">
    <!-- <ParaIdm> -->
    <!--<title>Swagger UI</title>-->
    <title>Swagger UI - Para CIC Msg Server</title>
    <!-- </ParaIdm> -->
    <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
    <link rel="icon" type="image/png" href="./favicon-32x32.png"
          sizes="32x32"/>
    <link rel="icon" type="image/png" href="./favicon-16x16.png"
          sizes="16x16"/>
    <style>
        html {
            box-sizing: border-box;
            overflow: -moz-scrollbars-vertical;
            overflow-y: scroll;
        }

        *, *:before, *:after {
            box-sizing: inherit;
        }

        body {
            margin: 0;
            background: #fafafa;
        }
    </style>
</head>

<body>
<div id="swagger-ui"></div>

<script src="./swagger-ui-bundle.js">

</script>
<script src="./swagger-ui-standalone-preset.js">

</script>
<script>
    window.onload = function () {
        var baseUrl = window.location.href.substring(0,
            window.location.href.lastIndexOf('/'));
        var _index = baseUrl.indexOf('#');
        if (_index > 0) {
            baseUrl = baseUrl.substring(0, _index);
            baseUrl = baseUrl.substring(0, baseUrl.lastIndexOf('/'));
        }
        // Build a system
        const ui = SwaggerUIBundle({
            // <ParaIdm>
            urls: [{
                url: baseUrl + "/../sample/openapi.json",
                name: "Swagger  V3"
            }],
            docExpansion: 'none',
            displayOperationId: false,
            operationsSorter: 'alpha',
            tagsSorter: 'alpha',
            // </ParaIdm>
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset],
            plugins: [SwaggerUIBundle.plugins.DownloadUrl],
            layout: "StandaloneLayout"
        })

        window.ui = ui
    }
</script>
</body>
</html>

step 5 : 配置到rest 体系中

// 这个配置为了核心的 openapi.json 数据 ,这是整个swagger 的核心
// 该配置不会自动注入 , 需要进行配置

// Jersey
@Component
@ApplicationPath("/sample")
public class JerseyConfig extends ResourceConfig {

    public JerseyConfig() {
        register(TestController.class);
        // --> here
        register(OpenApiResource.class);
    }

}

// spring other
    @Bean
    public OpenApiResource openApiResource() {
        return new OpenApiResource();
    }

总结

> swagger 的配置是多样的 , 这里只是其中一种

> index.html resource 是为了省事配置的路径 , 实际上可以通过配置静态路径放在合适的static 包下 ,我这种写法毕竟不规范

> 核心数据是 OpenApiResource.class 下 ,看一下源码就知道这个类的作用了 , 配置的方式很多 , 最终目的就是放入rest 管理

> 再一个核心就行openapi.yml 配置文件 , 正常配置到source 下即可 , 没什么特别的地方

> Maven 依赖这里是可以删的 , 自行尝试

附录

参考地址

https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started
// 可以参考 官方案例