首页 > 代码库 > Api管理工具(spring-rest-docs)

Api管理工具(spring-rest-docs)

对于app开发来说,必须需要有相应的api文档,一般最基础的就是用markdown工具来撰写api文档。当对于开发人员来说,是总会想着寻找更方便撰写,测试,对接前端开发的文档生成的工具。

其实这方面的工具很多:手动撰写的也很多,很多都带有mock测试功能。方便前端对接时使用。

国内的也不少:

RAP:动态生成模拟数据,实时测试等功能。

eoLinker:基于云端的api管理工具,同时提供在线协作,测试等的功能。

SBDoc:SBDoc是一个商业化开源产品,完全免费。无论你是前端工程师,还是后端工程师,接口永远都是两者交互的桥梁,所以SBDoc专为中小型团队量身打造,旨在解决接口的管理,测试与数据生成,实现真正的一体化解决方案。

Apizza - 为极客打造的api管理工具。

easyApi:有分免费和收费,但只支持在线版本的api管理。

CrapApi:一个由anjularjs+bootstrap+springMVC搭建的免费开源的API接口、文档管理系统(应用接口管理系统)。

showDoc:国内的api 管理工具,比较简洁。https://www.showdoc.cc/demo?page_id=10

小幼鸡:也是api 管理工具,差不多,自己可以比较试用,小幺鸡,简单好用的在线接口文档管理系统

NEI:团队协作工具,其实也是在文档等包括api接口的测试等的工具。https://nei.netease.com/

apiview:不多说就是一个工具。https://www.apiview.com/

apidoc:apidoc可以根据代码注释生成web api;没什么侵入性,可是学习成本稍微高点,要了解很多注释里使用到的注解

 

外国的Swagger 是一款java的api 生成工具,不过是代码侵入的形式,功能是很强大啊。可是代码里要加很多注解,让人别扭。

WSO2 API Management : 是比较好的api管理框架吧!

当然还有很多这种api管理工具,基本都是在云应用上,至少都有免费的。最好寻找离线的工具,可以在本地部署使用为最优了。

==========================================================================

下面重点介绍的是spring-rest-docs的使用。

spring-rest-docs是一个测试驱动的spring组件,他能生成测试成功的接口进行文档生成,支持markdown的转换或者html的转化,对于文档对接,其实也够了,缺点就是无法像其他工具那样模拟测试数据,前端在对接的时候,可以直接调用模拟数据,尤其对于赶进度的接口,可能是先写接口,再写实现,那么这样的话,就有点不适合。

但他的强大之处,就是可以自动生成文档,而且是经过测试过的接口,减去一些不必要的撰写工作,相对于Swagger来说,没有任何代码的依赖侵入。所以在实际的spring那套开发框架下,还是建议使用,他确实很不错。如果真的需要用到其他系统化的api管理工具,可以把markdown再导入到管理工具中去,即可。

另外apidoc 也不错,也是可以考虑使用的。

--------------------------------------------------------------------------------

spring-boot 整合 spring-rest-docs

1,pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.ouyang</groupId>
    <artifactId>boss</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>boss</name>
    <description>Demo project for Spring Boot</description>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.5.4.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>1.3.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.session</groupId>
            <artifactId>spring-session</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-websocket</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.restdocs</groupId>
            <artifactId>spring-restdocs-mockmvc</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- java-web-token 验证授权-->
        <dependency>
            <groupId>com.auth0</groupId>
            <artifactId>java-jwt</artifactId>
            <version>3.2.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt</artifactId>
            <version>0.7.0</version>
        </dependency>

        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.8.0</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <includes>
                        <include>**/*Test.java</include>
                    </includes>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.2</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html</backend>
                            <doctype>book</doctype>
                            <attributes>
                                <snippets>${project.build.directory}/generated-snippets</snippets>
                            </attributes>
                        <!--    <sourceDirectory>src/docs/asciidocs</sourceDirectory>
                            <outputDirectory>target/generated-docs</outputDirectory>-->
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <!--<plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-resources</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>copy-resources</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>
                                ${project.build.outputDirectory}/static/docs
                            </outputDirectory>
                            <resources>
                                <resource>
                                    <directory>
                                        ${project.build.directory}/generated-docs
                                    </directory>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>-->
        </plugins>
    </build>


</project>

2,写测试类

@RunWith(SpringRunner.class)
@WebMvcTest(TestController.class)
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class SpringRest2 {


    @Autowired
    private MockMvc mockMvc;

    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/xiaofeng").param("xiaobing", "Tester").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(document("index2", requestParameters(
                        parameterWithName("xiaobing").description("xiaobing is autoSelected avaible"))));
    }

//    @Test
//    public void shouldReturnDefaultMessage2() throws Exception {
//        this.mockMvc.perform(get("/api/liu").accept(MediaType.APPLICATION_JSON))
//                .andExpect(status().isOk())
//                .andDo(document("index"));
//    }


}

3,进行junit测试后在target目录下会生成

技术分享

然后再配置接口展示的文档:

技术分享

这里需要建立相应的文档,并建立index.adoc文件。{snippets} 就是你配置在asciidoctor-maven-plugin插件里的snippets属性

4,生成html文档

在控制台输入: mvnw package (或者mvn package)

会在target/generated-docs 里面生成对应的html文档。

技术分享

还有更好的用法,可以查看官方文档:

http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/

 

intellj可以按照asciiDoc插件 方便查看文档

 参考:spring-rest-docs https://github.com/sumit-samaddar/spring-rest-docs

官方地址:http://docs.spring.io/spring-restdocs/docs/1.1.0.RELEASE/reference/html5/

Api管理工具(spring-rest-docs)