Api管理工具（spring-rest-docs）

時間  2019-11-07
標籤 api 管理 工具 spring rest docs 欄目 Spring 简体版
原文   原文鏈接

對於app開發來講，必須須要有相應的api文檔，通常最基礎的就是用markdown工具來撰寫api文檔。當對於開發人員來講，是總會想着尋找更方便撰寫，測試，對接前端開發的文檔生成的工具。html

其實這方面的工具不少：手動撰寫的也不少，不少都帶有mock測試功能。方便前端對接時使用。前端

國內的也很多：html5

RAP：動態生成模擬數據，實時測試等功能。java

eoLinker：基於雲端的api管理工具，同時提供在線協做，測試等的功能。mysql

SBDoc：SBDoc是一個商業化開源產品，徹底免費。不管你是前端工程師，仍是後端工程師，接口永遠都是二者交互的橋樑，因此SBDoc專爲中小型團隊量身打造，旨在解決接口的管理，測試與數據生成，實現真正的一體化解決方案。git

Apizza - 爲極客打造的api管理工具。github

easyApi：有分免費和收費，但只支持在線版本的api管理。web

CrapApi：一個由anjularjs+bootstrap+springMVC搭建的免費開源的API接口、文檔管理系統（應用接口管理系統）。redis

showDoc：國內的api 管理工具，比較簡潔。https://www.showdoc.cc/demo?page_id=10spring

小幼雞：也是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/

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程