HttpDoc:一个HTTP RESTful API 在线文档阅览和接口测试以及SDK生成框架

HttpDoc

GitHub: https://github.com/core-lib/httpdoc

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

功能特性

  • 基础功能无需为配合HttpDoc框架而多写一句代码,甚至连doc注释都不必写,即可拥有项目的API文档和测试界面。
  • 遵循 RFC 2616 HTTP/1.1 规范,适配主流后台WEB框架。
  • 拓展多个 Java Doc 注释标签,满足不同的文档阅览及在线测试需求。
  • 一键生成SDK,支持多个平台,让前后台以及跨平台对接变得更简单。
  • WEB服务器无关,同时支持 Spring Boot 命令方式启动。
  • 支持 Maven Gradle 或JAR包依赖。

环境依赖

JDK 1.7 +

集成步骤

Maven

  1. 引入依赖

    
    
        
            jitpack.io
            https://www.jitpack.io
        
    

    
        
        
            com.github.core-lib.httpdoc
            httpdoc-spring-mvc
            v1.5.3
        
        
        
        
            com.sun
            tools
            1.8
            system
            ${env.JAVA_HOME}/lib/tools.jar
        
        
    

  1. 配置插件



    org.apache.maven.plugins
    maven-resources-plugin
    
        UTF-8
    
    
        
            copy-src
            process-sources
            
                copy-resources
            
            
                ${project.build.directory}/classes
                
                    
                        ${basedir}/src/main/java
                    
                
            
        
    

  1. 配置参数
  • SpringMVC

    • web.xml 中增加一个servlet和servlet-mapping标签
    
        
            httpdoc
            io.httpdoc.web.HttpdocServletSupport
            
                httpdoc
                项目名称
            
            
                version
                项目版本
            
            
                description
                
                    
                
            
            
                dateFormat
                yyyy-MM-dd HH:mm:ss
            
            1
        
        
        
            httpdoc
            /httpdoc.json
        
    
    
    • spring-servlet.xml 中增加一个标签以允许浏览器访问HttpDoc的页面静态资源
    
    
  • Spring Boot

    • 如果是Spring Boot项目则不需要上面SpringMVC的两个配置,实际上 Spring Boot 项目也没有web.xml文件来做配置。
    • 只需要将httpdoc-spring-mvc依赖替换成下面的依赖并在项目入口主类上标注一个@EnableHttpdoc() 注解即可,对应的参数也可以在注解上设置。
    
      com.github.core-lib.httpdoc
      httpdoc-spring-boot
      v1.5.3
    
    

参数说明

  • 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 HH:mm:ss
  • translator 文档翻译器,缺省为自动匹配当前项目的WEB框架
  • interpreter 文档解释器,缺省为源码解释器
  • serializer 文档序列化器,缺省为JSON序列化器,所以项目中需要依赖jackson-databind

在线示例

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

变更记录

  • v1.5.3
    • 优化项目依赖让项目集成更简单
    • 默认采用JSON文档序列化器
  • v1.5.2
    • 第一个正式版发布
  • v1.5.1
    • 增加示例模块
    • 增加README.md

协议声明

Apache-2.0

联系作者

QQ 646742615 不会钓鱼的兔子

你可能感兴趣的:(HttpDoc:一个HTTP RESTful API 在线文档阅览和接口测试以及SDK生成框架)