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 ...

随机推荐

oracle 解锁表的一个小问题
最近开发的时候遇到一个小问题,执行一段sql之后发现表被锁了显示错误为:ora-00054:resource busy and acquire with nowait specified 百度之后 ...
const 与指针
#include <iostream> using namespace std; int main() { // 第一种.使指针不能改动对象的值.注:此时指针能够指向另外的对象 int i ...
常见的web前端性能优化
一. 语义化HTML:语义化HTML的好处是可以使代码简洁清晰.支持不同设备.利于搜索引擎.便于团队开发: 减少DOM节点:加速页面渲染: 给图片加上正确的宽高值:这可以减少页面重绘,同时防止图片缩放 ...
vue - webpack.dev.conf.js
描述:开发时的配置.(配置开发时的一些操作) 例如这里,是否自动打开浏览器(默认true) 'use strict' // build/util.js const utils = require('. ...
Android 歌词显示
一.概述项目中设计到歌词显示的问题,这一块之前没有涉及过,只是套用过一个开源的项目,效果还行,于是想到拿来稍作修改,以适应项目需求. 二.歌词控件先来看下这个自定义控件写的歌词控件吧: publi ...
Xshell5 破解
Xshell5激活码 Xshell5激活方式Xshell5破解版 Xshell是一个用于MS Windows平台的强大的SSH,TELNET,和RLOGIN终端仿真软件.它使得用户能轻松和安全地从Wi ...
使用 dbdeploy.net 管理数据库变更
使用 dbdeploy.net 管理数据库变更没有包含数据库的持续集成都是假的.这可不是我说的.一直以来都没能找到一个理想的数据库变更管理工具.直到转了 java 再回来,才发现 dbdeploy ...
基于AndroidPn二次开发的可行性
一.背景如果要自己搭建,从零开始做或基于开源进行修改扩充,开源的push引擎,90%的博文首推AndroidPN,结合公司现状,最优解决方案就是进行AndroidPN的二次开发了.先看一下这个项目: ...
RabbitMQ的应用场景以及基本原理介绍(转载)
1.背景 RabbitMQ是一个由erlang开发的AMQP(Advanved Message Queue)的开源实现. 2.应用场景 2.1异步处理场景说明:用户注册后,需要发注册邮件和注册短信, ...
Image.Save出错 GDI 一般错误
一般是路径问题需要转化为绝对路径 \转换为/ if (HttpContext.Current!=null) outPath = HttpContext.Current.Server.MapPath( ...

swagger在线文档和离线文档

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

随机推荐

热门专题