jsondoc开发接口

前端与后端开发过程中总有先后过程。前后端联调的时候，也许后端开发人员以及忘记原先开发的代码接口情况。没有前端界面的支持对后端来说测试开发代码的功能也很费劲。

为方便提供接口给前端，也为了后端人员方便测试。我们可以使用jsondoc。

 

以下是springBoot框架下的环境搭建。

 

1.下载：http://start.spring.io  

    在search for dependencies框写入web

    然后点击Generate Project按钮 下载demo  

 

2.在pom.xml文件里配置

 

按如下配置：

    <properties>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <java.version>1.8</java.version>

        <spring.version>4.2.4.RELEASE</spring.version>

        <spring-boot.version>1.3.2.RELEASE</spring-boot.version>

        <platform-bom.version>2.0.2.RELEASE</platform-bom.version>

        <jsondoc.version>1.2.11</jsondoc.version>

    </properties>

 

加入jar：

（1）、加入 spring-boot-starter-jsondoc.jar

 

       <dependency>

            <groupId>org.jsondoc</groupId>

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

            <version>1.2.11</version>

        </dependency>

 

（2）、加入jsondoc-ui-webjar.jar

 

        <dependency>

            <groupId>org.jsondoc</groupId>

            <artifactId>jsondoc-ui-webjar</artifactId>

            <version>1.2.11</version>

        </dependency>

 

（3）、加入 spring-boot-starter-web

 

        <dependency>

            <groupId>org.springframework.boot</groupId>

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

        </dependency>

 

（4）、加入spring-boot-starter-test.jar

 

        <dependency>

            <groupId>org.springframework.boot</groupId>

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

            <scope>test</scope>

        </dependency>

 

（5）、加入platform-bom.jar

        <dependency>

            <groupId>io.spring.platform</groupId>

            <artifactId>platform-bom</artifactId>

            <version>${platform-bom.version}</version>

            <type>pom</type>

            <scope>import</scope>

       </dependency>

 

加入maven-compiler-plugin插件：

<plugin>

     <artifactId>maven-compiler-plugin</artifactId>

     <version>3.3</version>

     <configuration>

     <source>1.8</source>

     <target>1.8</target>

     </configuration>

</plugin>

 

－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－

 

因为我们公司的项目已经引入相关包文件、我在pom文件只要加2个jar

（1）、加入 spring-boot-starter-jsondoc.jar

 

       <dependency>

            <groupId>org.jsondoc</groupId>

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

            <version>1.2.11</version>

        </dependency>

 

（2）、加入jsondoc-ui-webjar.jar

 

        <dependency>

            <groupId>org.jsondoc</groupId>

            <artifactId>jsondoc-ui-webjar</artifactId>

            <version>1.2.11</version>

        </dependency>

－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－－

 

3.在resource包下，application.properties配置如下：

# mandatory configuration

jsondoc.version=1.0        //jsondoc的版本

jsondoc.basePath=http://localhost:8080      //路径是本机，端口8080

jsondoc.packages[0]=org.mvnsearch.jsondoc.controller     // 扫描路径下的包

 

# optional configuration

jsondoc.playgroundEnabled=true

jsondoc.displayMethodAs=URI

 

所遇问题：jsondoc.packages[0]必须为数组，否则api下无内容

 

至此我们的jsondoc环境已经准备完毕，接下来我们在controller中添加注解

 

4.在controller加入注解如下：

 

class的注解

@RestController         //rest风格

@RequestMapping(value = “/user")       //映射路径

@Api(description = "会员服务", name = "UserService", group =“ 范围内容”）

@ApiAuthToken(testtokens = “user")  //设置testtokens的值,testtokens的值可以写死

 

方法注解

@RequestMapping(“/{id}”)        //映射路径

@ApiMethod(id = "Find_user_one", description = "根据会员ID查找会员", summary = "Gets a book given the book ID”)            //Api方法

@@ApiAuthNone

public User show(@ApiQueryParam(name = "id", description = "主键id", format = "Integer") @RequestParam Integer id)       //获取路径下的id、user id、type

 

 

5.所遇到问题：显示不出jsondoc-ui.html的页面

  原因：项目中的拦截器拦截了，可以通过builder.addExcludedPath("/jsondoc-ui.html");

                                                                   builder.addExcludedPath("/webjars/**");来解决

 

 

6.删掉document文件夹就不会显示Overview，删除authentication.html、domain－diagram.html 、http-response-codes.html、http-verbs.html、ubiquitous-language.html不会显示Overview下面的链接