swagger在线文档和离线文档

spring boot项目的swagger文档。

依赖从spring boot的基础上增加。参考pom.xml：

　　　　　　　　　　<dependency>

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

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

		</dependency>

		<dependency>

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

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

			<scope>test</scope>

		</dependency>

		<!-- Swagger  -->
　　　　　　　　　　<!-- 文档可视化-->

		<dependency>

			<groupId>io.springfox</groupId>

			<artifactId>springfox-swagger-ui</artifactId>

			<version>2.6.1</version>

		</dependency>

		<dependency>

			<groupId>io.springfox</groupId>

			<artifactId>springfox-swagger2</artifactId>

			<version>2.6.1</version>

		</dependency>

		<dependency>

			<groupId>org.json</groupId>

			<artifactId>json</artifactId>

		</dependency>

		<dependency>

            <groupId>org.springframework.restdocs</groupId>

            <artifactId>spring-restdocs-mockmvc</artifactId>

            <scope>test</scope>

        </dependency>

                <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-staticdocs</artifactId>

            <version>2.6.1</version>

        </dependency>

        <dependency>

            <groupId>com.alibaba</groupId>

            <artifactId>fastjson</artifactId>

            <version>1.2.8</version>

        </dependency>

　　maven插件：

<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>**/*Documentation.java</include>

                    </includes>

                </configuration>

            </plugin>

            <plugin>

                <groupId>org.asciidoctor</groupId>

                <artifactId>asciidoctor-maven-plugin</artifactId>

                <version>1.5.3</version>

                <!-- Configure generic document generation settings -->

                <configuration>

                    <sourceDirectory>${project.basedir}/target/asciidoc</sourceDirectory>

                    <sourceDocumentName>paths.adoc</sourceDocumentName>

                    <attributes>

                        <doctype>book</doctype>

                        <toc>left</toc>

                        <toclevels>3</toclevels>

                        <numbered></numbered>

                        <hardbreaks></hardbreaks>

                        <sectlinks></sectlinks>

                        <sectanchors></sectanchors>

                        <generated>${project.build.directory}/asciidoc</generated>

                    </attributes>

                </configuration>

                <!-- Since each execution can only handle one backend, run

                     separate executions for each desired output type -->

                <executions>

                    <execution>

                        <id>output-html</id>

                        <phase>test</phase>

                        <goals>

                            <goal>process-asciidoc</goal>

                        </goals>

                        <configuration>

                            <backend>html5</backend>

                            <outputDirectory>${project.basedir}/docs/asciidoc/html</outputDirectory>

                        </configuration>

                    </execution>

                </executions>

            </plugin>

		</plugins>

	</build>

Swagger2.java参考代码：

import java.util.ArrayList;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.ComponentScan;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.bind.annotation.RequestMethod;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.builders.ResponseMessageBuilder;

import springfox.documentation.schema.ModelRef;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.ResponseMessage;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@ComponentScan

@EnableSwagger2

public class Swagger2 {

	@Bean

	public Docket petApi() {

		//自定义异常信息

		 ArrayList<ResponseMessage> responseMessages = new ArrayList<ResponseMessage>() {{

	            add(new ResponseMessageBuilder().code(200).message("成功").build());

	            add(new ResponseMessageBuilder().code(400).message("请求参数错误").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(401).message("权限认证失败").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(403).message("请求资源不可用").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(404).message("请求资源不存在").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(409).message("请求资源冲突").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(415).message("请求格式错误").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(423).message("请求资源被锁定").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(501).message("请求方法不存在").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(503).message("服务暂时不可用").responseModel(new ModelRef("Error")).build());

	            add(new ResponseMessageBuilder().code(-1).message("未知异常").responseModel(new ModelRef("Error")).build());

	        }};

		return new Docket(DocumentationType.SWAGGER_2)

				.apiInfo(apiInfo())

				.select()

				.apis(RequestHandlerSelectors.basePackage("my.product.controller"))//扫描的API包

				.paths(PathSelectors.any())

				.build()

				.useDefaultResponseMessages(false)

                .globalResponseMessage(RequestMethod.GET, responseMessages)

                .globalResponseMessage(RequestMethod.POST, responseMessages)

                .globalResponseMessage(RequestMethod.PUT, responseMessages)

                .globalResponseMessage(RequestMethod.DELETE, responseMessages);

	}

	private ApiInfo apiInfo() {

		return new ApiInfoBuilder()

				.title("Spring cloud 中使用Swagger2构建Restful APIs")

				.description("swagger项目文档测试说明")

				.version("1.0").build();

	}

}

　　TestController.java参考代码

import org.springframework.http.MediaType;

import org.springframework.web.bind.annotation.RequestBody;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RequestParam;

import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

@Api(value = "学生信息查询", description = "学生基本信息操作API", tags = "StudentApi", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)

@RestController

public class Swagger2TestController {

    @ApiOperation(value = "getStudent", notes = "依据学生姓名查询学生信息")

    @RequestMapping(value = "student", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)

    public Student getStudent(@RequestParam("name") String name){

    	System.out.println("name : "+name);

        Student reponse = new Student();

        reponse.setId(1);

        reponse.setName(name);

        reponse.setAge(12);

        reponse.setCls("二年级");

        reponse.setAddress("重庆市大竹林");

        reponse.setSex("男");

        return reponse;

    }

    @ApiOperation(value = "addStudent", notes = "添加一个学生", code = 201)

    @RequestMapping(value = "addStudent", method = RequestMethod.POST, consumes = MediaType.APPLICATION_JSON_VALUE)

    public void addStudent(@RequestBody Student student){

    	System.out.println("addStudent : "+student);

        return ;

    }

}

　　student.java参考代码

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "Student", description = "学生信息描述")

public class Student {

	/**

     * 学号

     */

    @ApiModelProperty("学号")

    private int id;

    /**

     * 姓名

     */

    @ApiModelProperty("姓名")

    private String name;

    /**

     * 年龄

     */

    @ApiModelProperty("年龄")

    private int age;

    /**

     * 性别

     */

    @ApiModelProperty("性别")

    private String sex;

    /**

     * 班级

     */

    @ApiModelProperty("班级")

    private String cls;

    /**

     * 住址

     */

    @ApiModelProperty("家庭住址")

    private String address;

	public int getId() {

		return id;

	}

	public void setId(int id) {

		this.id = id;

	}

	public String getName() {

		return name;

	}

	public void setName(String name) {

		this.name = name;

	}

	public int getAge() {

		return age;

	}

	public void setAge(int age) {

		this.age = age;

	}

	public String getSex() {

		return sex;

	}

	public void setSex(String sex) {

		this.sex = sex;

	}

	public String getCls() {

		return cls;

	}

	public void setCls(String cls) {

		this.cls = cls;

	}

	public String getAddress() {

		return address;

	}

	public void setAddress(String address) {

		this.address = address;

	}

}

　　测试类：

import org.junit.After;

import org.junit.Test;

import org.junit.runner.RunWith;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;

import org.springframework.boot.test.context.SpringBootTest;

import org.springframework.http.MediaType;

import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;

import org.springframework.test.context.junit4.SpringRunner;

import org.springframework.test.web.servlet.MockMvc;

import com.alibaba.fastjson.JSON;

import com.swagger.model.Student;

import io.github.robwin.markup.builder.MarkupLanguage;

import io.github.robwin.swagger2markup.GroupBy;

import io.github.robwin.swagger2markup.Swagger2MarkupConverter;

import springfox.documentation.staticdocs.SwaggerResultHandler;

import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;

import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;

import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.post;

@AutoConfigureMockMvc

@AutoConfigureRestDocs(outputDir = "target/generated-snippets")

@RunWith(SpringRunner.class)

@SpringBootTest

public class SwaggerApplicationTests {

	 private String snippetDir = "target/generated-snippets";

	 private String outputDir = "target/asciidoc";

	 @Autowired

	 private MockMvc mockMvc;

	 @After

	    public void Test() throws Exception{

	        // 得到swagger.json,写入outputDir目录中

	        mockMvc.perform(get(Swagger2Controller.DEFAULT_URL).accept(MediaType.APPLICATION_JSON))

	                .andDo(SwaggerResultHandler.outputDirectory(outputDir).build())

	                .andExpect(status().isOk())

	                .andReturn();

	        // 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir

	        // 这个outputDir必须和插件里面<generated></generated>标签配置一致

	        Swagger2MarkupConverter.from(outputDir + "/swagger.json")

	                .withPathsGroupedBy(GroupBy.TAGS)// 按tag排序

	                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式

	                .withExamples(snippetDir)

	                .build()

	                .intoFolder(outputDir);// 输出

	    }

	@Test

	public void contextLoads() throws Exception {

		 mockMvc.perform(get("/student").param("name", "xxx")

	                .accept(MediaType.APPLICATION_JSON))

	                .andExpect(status().isOk())

	                .andDo(MockMvcRestDocumentation.document("getStudent", preprocessResponse(prettyPrint())));

	        Student student = new Student();

	        student.setName("xxx");

	        student.setAge(23);

	        student.setAddress("湖北麻城");

	        student.setCls("二年级");

	        student.setSex("男");

	        mockMvc.perform(post("/addStudent").contentType(MediaType.APPLICATION_JSON)

	                .content(JSON.toJSONString(student))

	                .accept(MediaType.APPLICATION_JSON))

	                .andExpect(status().is2xxSuccessful())

	                .andDo(MockMvcRestDocumentation.document("addStudent", preprocessResponse(prettyPrint())));

	}

}

　　每个API都需要测试一下才有效。测试完后直接install，这离线文档就会在${product.path}\docs\asciidoc\html下生成。

在线文档启动项目访问http://localhost:8080/swagger-ui.html就行了。springboot启动类加@EnableSwagger2 注解就行

swagger在线文档和离线文档的更多相关文章

Swagger接口如何生成Html离线文档
A very simple tool that converts Swagger Api Document to Html File. 小记Swagger接口生成Html离线文档由来很多人用swa ...
spring boot利用swagger和spring doc生成在线和离线文档
参考博客地址: 在线文档:http://blog.didispace.com/springbootswagger2/ 离线文档:http://www.jianshu.com/p/af7a6f29bf4 ...
在.Net Core WebAPI下给Swagger增加导出离线文档功能
一丶前言最近刚接触到Swagger,在github上下载了它的源码和demo学习了一遍,发现这个组件非常好用,不过不足的是它没有导出离线文档的功能,于是乎我就想给它加一个导出功能 Swagger G ...
JDK8 API离线文档免费下载&JavaEE API文档离线下载&API在线查看链接&常用的JAR包下载
1.JDK8 API离线文档链接:https://pan.baidu.com/s/1fYc-QesmYRumTEPmnSgEKA 提取码:2bdr 2.JavaEE API文档离线下载链接:htt ...
Swagger在线文档使用教程
springboot整合Swagger2 1.首先创建一个springboot工程,在pom文件内导入依赖  <!--Swagger2- ...
cocos2d-x3.6 生成带类图的离线文档
我的博客:http://blog.csdn.net/dawn_moon cocos2d-x的官网有点慢,并且最新3.6的在线API文档居然没有了类图,不知道什么原因,之前2.2.6都是有的. 只是能够 ...
使用swagger作为restful api的doc文档生成
初衷记得以前写接口,写完后会整理一份API接口文档,而文档的格式如果没有具体要求的话,最终展示的文档则完全决定于开发者的心情.也许多点,也许少点.甚至,接口总是需要适应新需求的,修改了,增加了,这份 ...
Java实现office文档与pdf文档的在线预览功能
最近项目有个需求要java实现office文档与pdf文档的在线预览功能,刚刚接到的时候就觉得有点难,以自己的水平难以在三四天做完.压力略大.后面查找百度资料.以及在同事与网友的帮助下,四天多把它做完 ...
如何解决Android SDK中离线文档打开慢的问题
原文:http://blog.csdn.net/hansel/article/details/39268511 Android SDK中的离线文档虽然都是本地文件,但是有很多Javascript, C ...

随机推荐

【云计算】k8s相关资料
参考资料: How to get started, and achieve tasks, using Kubernetes:http://kubernetes.io/docs/getting-star ...
职场二年级转型C++的困惑
[来信] 老师.你好.看了你的博客和採訪.不由主自地给你发私信,感觉你能解答我的问题. 学生90后,2012年毕业于某不知名院校.两年工作经验(第一年C#,第二年java,直到如今),一直想转型C++ ...
极客技术专题【011期】：EasyUI初级教程
来源:GBin1.com 技术专题:EasyUI初级教程分享人:极客标签技术编辑 - html580(请站内关注分享人) 资深Web前端工程师,HTML580创始人,目前就职于广州一间软件公司.多年 ...
lua coroutine
Lua中协程都放在表coroutine中. Lua协程的四个状态挂起(suspended):一个协程被创建的时候,处于挂起状态,不会自动运行. 运行(running):coroutine.resum ...
Eleven puzzle_hdu_3095(双向广搜).java
Eleven puzzle Time Limit: 20000/5000 MS (Java/Others) Memory Limit: 32768/32768 K (Java/Others) T ...
算法笔记_099:蓝桥杯练习算法提高排列数（Java）
目录 1 问题描述 2 解决方案 1 问题描述问题描述 0.1.2三个数字的全排列有六种,按照字母序排列如下: 012.021.102.120.201.210 输入一个数n 求0~9十个数的全排 ...
Hibernate 主配置文件详解
摘要: 版权声明:本文为博主原创文章,如需转载请标注转载地址. 博客地址:http://www.cnblogs.com/caoyc/p/5595870.html 一.主配置文件命名规则 1.默认名称: ...
LR11.50 通过Mobile Application 录制手机操作
LR11.50 通过Mobile Application 录制手机操作步骤就是 1:新建LR脚本.协议选择Mobile Application - HTTP/HTML 2:在record里选择第三个 ...
一个表中的字段值用作另一个表的In查询条件
Question表与Paper表 Paper表中字段QuestionIds存储的是Question表中字段Id的拼接后的值如: 'f855eba1-b308-4bd7-a250-c071a0e1bd ...
【原创】说说JSON和JSONP，也许你会豁然开朗，含jQuery用例
说到AJAX就会不可避免的面临两个问题,第一个是AJAX以何种格式来交换数据?第二个是跨域的需求如何解决?这两个问题目前都有不同的解决方案,比如数据可以用自定义字符串或者用XML来描述,跨域可以通过服 ...

swagger在线文档和离线文档

swagger在线文档和离线文档的更多相关文章

随机推荐

热门专题