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

随机推荐

Strategy Pattern（策略模式）
Head First定义: 策略模式定义了算法族,分别封装起来,让他们之间可以互相替换,此模式让算法的变化独立于使用算法的客户. 策略模式的设计原则主要有三个: 找出应用中可能需要变化的部分,把它们独 ...
python中子类调用父类的方法
1子类调用父类构造方法 class Animal(object): def __init__(self): print("init Animal class~") def run( ...
SQL Server-数据库中强varchar类型使用sum函数计算总和
select sum(cast(totalmoney AS DECIMAL)) as totalmoney from dbo.t_wxbill
vue组件属性中字符串如何拼接变量？
不得不说,对于水平只有jquery的vue初学者来说,vue的图片加载实现确实挺坑的,在文档中也没有看到说明.经过百度之后终于知道了什么情况. 首先: 这样是没问题的: <img src=&qu ...
[Webpack] Detect Unused Code with Webpack and unused-files-webpack-plugin
As you refactor and modify applications, it's difficult to manage and keep track of files as they be ...
一个Tomcat配置参数引发的血案
转载:https://mp.weixin.qq.com/s/3IuTcDCTB3yIovp6o_vuKA 一.现象有用户反馈访问PC首页偶尔会出现白页情况,也偶尔会收到听云的报警短信二.监控(听云 ...
OpenCV 4.1 编译和配置
OpenCV 4.0 版本,历时3年半,终于在2018年圣诞节前发布了,该版本增加的新功能如下: 1) 更新代码支持 c++11 特性,需要兼容 c++11 语法的编译器 2)增加 dnn 中的模块功 ...
企业建站系统MiinCMP1.0.5 标准版公布!
2014-5-6日,Juuluu公布其企业建站系统MiinCMP1.0.5 标准版,1.0.5是一款相对成熟的企业站点解决方式.执行MiinCMP1.0.5,仅仅需2M的mysql,50m的java空 ...
Android4.4 SystemUI加入Dialog弹窗
此弹窗为开机SystemUI的显示弹窗: 首先.在SystemUI的源代码文件夹加入源代码类文件,文件夹为frameworks/base/packages/SystemUI/src/com/andro ...
关于spring中<context:component-scan base-package="" />写法
1.通配符形式<context:component-scan base-package="com.*" /> 2.全路径 <context:component-s ...

swagger在线文档和离线文档

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

随机推荐

热门专题