曾静的博客

但行好事,莫问前程.

嗨,我是曾静 (@devzeng),目前暂居深圳。


这是我用来记录平日学习笔记的地方,欢迎您的访问.

Jersey整合Swagger自动生成API文档

之前写过一篇文章《使用Jersey开发REST服务》,里面简单介绍了使用Jersey来快速创建REST的API服务。

REST API都是要对外提供服务的,那么文档是必须的。经常要给其他人员提供文档,每次都是要不断的维护word/excel的文件,挺麻烦的。能不能做到自动生成呢?答案是可以的,swagger就是这样的一个组件帮助我们快速生成,让开发人员只需要关注功能的开发即可,后续的工作就交给Swagger就好了。

下面简单介绍下如何在Jersey的项目中集成Swagger。

1、pom.xml加入swagger的依赖

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jersey2-jaxrs</artifactId> 
    <version>1.5.0</version>
</dependency>

2、修改web.xml配置

(1) 修改Jersey配置

<!-- jersey -->
<servlet>
    <servlet-name>jersey</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.packages</param-name>
        <param-value>io.swagger.jaxrs.listing,com.devzeng.service.schedule.api</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>jersey</servlet-name>
    <url-pattern>/api/*</url-pattern>
</servlet-mapping>

(2)新增swagger配置

<!-- swagger -->
<servlet>
    <servlet-name>Jersey2Config</servlet-name>
    <servlet-class>io.swagger.jersey.config.JerseyJaxrsConfig</servlet-class>
    <init-param>
        <param-name>api.version</param-name>
        <param-value>1.0.0</param-value>
    </init-param>
    <init-param>
        <param-name>swagger.api.basepath</param-name>
        <param-value>http://localhost:8080/api</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
</servlet>

说明:

  • swagger.api.basepath:这个是api访问的baseurl

3、配置注解

4、配置swagger-ui

(1) 下载swagger-ui

https://github.com/swagger-api/swagger-ui

推荐使用2.x版本

(2) 拷贝dist目录下面的文件到webroot下面

(3) 修改index.html页面的url地址

url = "http://localhost:8080/api/swagger.json";

生成的文档效果如下:

swagger-demo.jpg

参考资料

1、Swagger Core Jersey 2.X Project Setup 1.5

2、Swagger-Core Annotations

最近的文章

Eclipse无法正常启动Tomcat项目解决办法

以前一直使用 MyEclipse 开发 JavaEE 项目,实在是太卡了,近期将之前的项目全部迁移到了 Eclipse 上面。一段时间内都好好的,这两天突然发现启动 Tomcat 不正常了,具体表现如下:(1)Tomcat 在 Eclipse 里面能正常启动,但在浏览器中访问http://localhost:8080/报404错误。也就是说 Tomcat 启动了但是里面部署的 web 项目没有启动。(2)关闭 Eclipse 里面的 Tomcat,在 Tomcat 安装目录下双击start...…

Java继续阅读
更早的文章

Windows环境下OpenSSL的编译和使用

OpenSSL是目前使用的非常广泛的加密算法库,基本上我们日常使用到的HTTPS、SSH都离不开它的身影。本文就在Windows环境下面编译最新版本的OpenSSL的步骤进行整理。编译OpenSSL1.编译环境准备(1) perlOpenSSL的编译需要使用到perl的环境,如果之前安装过可以跳过此步骤。1) 下载perl安装包根据操作系统的版本下载对应最新版本的perl(当前最新的版本是5.22.3.2204),下载地址是:https://www.activestate.com/acti...…

C++继续阅读