程序文档工具swagger-ui-theme、HttpDoc、spring-boot-starter-swagger介绍

以下为你介绍的程序文档工具都可用在Linux系统上:swagger-ui-theme(蚀刻 swagger-ui 主题)、HttpDoc(零侵入的 RESTful API 文档框架)、spring-boot-starter-swagger(简化使用 Swagger2 的整合代码)。

1、swagger-ui-theme(蚀刻 swagger-ui 主题)

swagger-ui-theme 自己编写的SwaggerUI的一个主题,是一个纯前端项目。

应用技术:

react + UMI + DVA + Ant Design

原理:

对swagger的json字符串进行解析,然后将解析到的字符串做一定转换,展示到这套UI主题上。

特点:

swagger ui theme与原来的swagger ui,整体结构改为了左右结构。

请求参数划分的更清晰(界面中明确区分:普通表单,request body,request header)。

解决了原swagger-ui,post文件下载时,如果下载文件名是中文,是一串转义字符串的问题(不过要后端要按照要求进行相关设置)。

支持api搜索。

支持中/英文切换。

文档地址输入框能自动提示文,避免记不住swagger文档的json字符串地址的尴尬。

不足:

暂不支持文件上传接口的测试。

部署方式和二次开发方式:

详见项目的README.md文档,此处不再赘述。

源码地址:

github: https://github.com/free-pan/swagger-ui-theme.git

gitee: https://gitee.com/free_pan/swagger-ui-theme.git

部分截图:

程序文档工具swagger-ui-theme、HttpDoc、spring-boot-starter-swagger介绍

程序文档工具swagger-ui-theme、HttpDoc、spring-boot-starter-swagger介绍

程序文档工具swagger-ui-theme、HttpDoc、spring-boot-starter-swagger介绍

下载地址:https://gitee.com/free_pan/swagger-ui-theme

2、HttpDoc(零侵入的 RESTful API 文档框架)

HttpDoc-基于Java标准doc注释构建的代码零侵入的HTTP RESTful API在线阅览文档及测试界面框架。

JSON-Editor: httpdoc-ui TextArea: httpdoc-ui-v1

功能特性:

基础功能无需为配合HttpDoc框架而多写一句代码,甚至连doc注释都不必写,即可拥有项目的API文档和测试界面。

遵循 RFC 2616 HTTP/1.1 规范,适配主流后台WEB框架。

拓展多个 Java Doc 注释标签,满足不同的文档阅览及在线测试需求。

一键生成SDK,支持多个平台,让前后台以及跨平台对接变得更简单。

WEB服务器无关,同时支持 Spring Boot 命令方式启动。

支持 Maven Gradle 或JAR包依赖。

环境依赖:

JDK 1.7 +

集成步骤:

Maven:

引入依赖:

<project>

<!-- 设置 jitpack.io 仓库 -->

<repositories>

<repository>

<id>jitpack.io</id>

<url>https://www.jitpack.io</url>

</repository>

</repositories>

<dependencies>

<!-- 添加 HttpDoc 依赖 -->

<dependency>

<groupId>com.github.core-lib.httpdoc</groupId>

<artifactId>httpdoc-spring-mvc</artifactId>

<version>v1.5.3</version>

</dependency>

<!-- 添加JDK的tools.jar依赖用于解析源码注释,采用这种方式部署到Tomcat时需要往Tomcat的lib目录增加该tools.jar -->

<dependency>

<groupId>com.sun</groupId>

<artifactId>tools</artifactId>

<version>1.8</version>

<scope>system</scope>

<systemPath>${env.JAVA_HOME}/lib/tools.jar</systemPath>

</dependency>

<!-- 当然还有很多种方式来依赖tools.jar,例如上传到自己的私服或从别的仓库中依赖进来 -->

</dependencies>

</project>

配置插件:

<!-- 由于框架基于源码注释解析来实现,所以保留源码是基础,如果只想要在线测试而没有文档阅览的需求,可不必添加该插件。-->

<!-- 如果项目是多模块项目,需要被解析的源码类分散在多模块中,则其他模块也需要配置该插件,或在父项目的pom.xml中配置该插件。-->

<plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-resources-plugin</artifactId>

<version>3.1.0</version>

<configuration>

<encoding>UTF-8</encoding>

</configuration>

<executions>

<execution>

<id>copy-src</id>

<phase>process-sources</phase>

<goals>

<goal>copy-resources</goal>

</goals>

<configuration>

<outputDirectory>${project.build.directory}/classes</outputDirectory>

<resources>

<resource>

<directory>${basedir}/src/main/java</directory>

</resource>

</resources>

</configuration>

</execution>

</executions>

</plugin>

配置参数:

SpringMVC:

<web-app>

<servlet>

<servlet-name>httpdoc</servlet-name>

<servlet-class>io.httpdoc.web.HttpdocServletSupport</servlet-class>

<init-param>

<param-name>httpdoc</param-name>

<param-value>项目名称</param-value>

</init-param>

<init-param>

<param-name>version</param-name>

<param-value>项目版本</param-value>

</init-param>

<init-param>

<param-name>description</param-name>

<param-value>

<![CDATA[

项目描述(可以内嵌HTML标签)

]]>

</param-value>

</init-param>

<init-param>

<param-name>dateFormat</param-name>

<param-value>yyyy-MM-dd</param-value>

</init-param>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>httpdoc</servlet-name>

<url-pattern>/httpdoc.json</url-pattern>

</servlet-mapping>

</web-app>

<mvc:resources mapping="/httpdoc-ui/**" location="classpath:/META-INF/resources/httpdoc-ui/"/>

spring-servlet.xml 中增加一个标签以允许浏览器访问HttpDoc的页面静态资源。

web.xml 中增加一个servlet和servlet-mapping标签。

Spring Boot:

<dependency>

<groupId>com.github.core-lib.httpdoc</groupId>

<artifactId>httpdoc-spring-boot</artifactId>

<version>v1.5.3</version>

</dependency>

如果是Spring Boot项目则不需要上面SpringMVC的两个配置,实际上 Spring Boot 项目也没有web.xml文件来做配置。

只需要将httpdoc-spring-mvc依赖替换成下面的依赖并在项目入口主类上标注一个@EnableHttpdoc() 注解即可,对应的参数也可以在注解上设置。

参数说明:

httpdoc 项目名称,缺省为HttpDoc

version 项目版本,缺省为1.0.0

description 项目描述,可以用套起来并使用HTML标签语法

protocol 访问协议,http或https,缺省为request.getProtocol();

hostname 主机名,缺省为request.getServerName();

port 端口号,缺省为request.getServerPort();

context 容器路径,缺省为request.getContextPath();

dateFormat 日期格式,缺省为yyyy-MM-dd

translator 文档翻译器,缺省为自动匹配当前项目的WEB框架

interpreter 文档解释器,缺省为源码解释器

serializer 文档序列化器,缺省为JSON序列化器,所以项目中需要依赖jackson-databind

在线示例:

项目中的httpdoc-sample模块就是一个HttpDoc + SpringMVC的一个标准示例,可checkout后查看源码和编译运行查看效果,也可立即预览:JSON-Editor: httpdoc-ui TextArea: httpdoc-ui-v1

变更记录:

v1.5.8:

增加Schema的全局设置

适配递归Schema的问题

v1.5.7:

增加JSONEditor的前端实现

增加@style标签用于控制参数展示的样式

v1.5.6:

修复带中文或空格路径的解析失败bug

适配Unix系统路径分隔符

注释读取日志显示

v1.5.5:

增加Lifecycle接口让实现类可以监听initial和destroy事件以及用户配置信息

v1.5.4:

极大提升源码注释解析速度

修复spring-boot模块的依赖,增加spring-mvc依赖

v1.5.3:

优化项目依赖让项目集成更简单

默认采用JSON文档序列化器

v1.5.2:

第一个正式版发布

v1.5.1:

增加示例模块

增加README.md

协议声明:

Apache-2.0

下载地址:https://gitee.com/mirrors/HttpDoc

3、spring-boot-starter-swagger(简化使用 Swagger2 的整合代码)

该项目主要利用Spring Boot的自动化配置特性来实现快速地将swagger2引入spring boot应用来生成API文档,简化原生使用swagger2的整合代码。

如何使用:

在该项目的帮助下,我们的Spring Boot可以轻松的引入swagger2,主需要做下面两个步骤:

在pom.xml中引入依赖:

当前最新版本 1.7.0.RELEASE:

<dependency>

<groupId>com.spring4all</groupId>

<artifactId>swagger-spring-boot-starter</artifactId>

<version>1.7.0.RELEASE</version>

</dependency>

注意:从1.6.0开始,我们按Spring Boot官方建议修改了artifactId为swagger-spring-boot-starter,1.6.0之前的版本不做修改,依然为使用spring-boot-starter-swagger!

在应用主类中增加@EnableSwagger2Doc注解:

@EnableSwagger2Doc

@SpringBootApplication

public class Bootstrap {

public static void main(String[] args) {

SpringApplication.run(Bootstrap.class, args);

}

}

默认情况下就能产生所有当前Spring MVC加载的请求映射文档。

下载地址:https://gitee.com/didispace/spring-boot-starter-swagger

注明

以上就是程序文档工具swagger-ui-theme、HttpDoc、spring-boot-starter-swagger的介绍内容,这些程序文档工具都能使用在Linux操作系统中。

栏目相关文章