Swagger V3 Java 整合记录

╰半橙微兮° 2023-06-16 05:00 14阅读 0赞

# 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>
                    <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>
    
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        
        
        <title>Swagger UI - Para CIC Msg Server</title>
        
        <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
    // 可以参考 官方案例