Swagger V3 Java 整合记录
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.v3groupId>
<artifactId>swagger-annotationsartifactId>
<version>${swagger-core.version}version>
<exclusions>
<exclusion>
<groupId>com.fasterxml.jackson.datatypegroupId>
<artifactId>jackson-dataformat-yamlartifactId>
exclusion>
exclusions>
dependency>
<dependency>
<groupId>io.swagger.core.v3groupId>
<artifactId>swagger-jaxrs2-servlet-initializerartifactId>
<version>${swagger-core.version}version>
dependency>
<dependency>
<groupId>io.swagger.core.v3groupId>
<artifactId>swagger-jaxrs2artifactId>
<version>${swagger-core.version}version>
dependency>
<dependency>
<groupId>io.swagger.core.v3groupId>
<artifactId>swagger-annotationsartifactId>
<version>${swagger-core.version}version>
<exclusions>
<exclusion>
<groupId>com.fasterxml.jackson.datatypegroupId>
<artifactId>jackson-dataformat-yamlartifactId>
exclusion>
exclusions>
dependency>
<dependency>
<groupId>org.webjarsgroupId>
<artifactId>swagger-uiartifactId>
<version>${swagger-ui.version}version>
dependency>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-resources-pluginartifactId>
<inherited>trueinherited>
<executions>
<execution>
<id>copy-swagger-resources-in-placeid>
<phase>process-resourcesphase>
<goals>
<goal>copy-resourcesgoal>
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.htmlexclude>
excludes>
resource>
resources>
configuration>
execution>
executions>
plugin>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-dependency-pluginartifactId>
<inherited>trueinherited>
<executions>
<execution>
<phase>generate-resourcesphase>
<goals>
<goal>unpackgoal>
goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.webjarsgroupId>
<artifactId>swagger-uiartifactId>
<version>${swagger-ui.version}version>
<overWrite>trueoverWrite>
<outputDirectory>${project.build.directory}/swagger-uioutputDirectory>
<excludes>**/*.gzexcludes>
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: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
step 4 : 主界面 index.html
放在 Resource / META-INF/resources/swagger下 ,手动创建的文件夹
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI - Para CIC Msg Servertitle>
<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({
// 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
// 可以参考 官方案例