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

随机推荐

抓取网页图片的脚本(javascript)
抓取网页图片的脚本(javascript) 本文地址: http://blog.csdn.net/caroline_wendy/article/details/24172223 脚本内容 (没有换行) ...
直接插入排序、折半插入排序、shell插入排序
直接插入排序: 折半插入排序: shell插入排序:
Core Data NSAttribute Type 数据类型
一:使用Core Data 的可用数据类型 NSAttributeType Defines the possible types of NSAttributeType properties. Thes ...
Flutter常用布局组件
Flutter控件本身通常由许多小型.单用途的控件组成,结合起来产生强大的效果,例如,Container是一种常用的控件,由负责布局.绘画.定位和大小调整的几个控件组成,具体来说,Container是 ...
赵雅智_service生命周期
Android中的服务和windows中的服务是类似的东西,服务一般没实用户操作界面.它执行于系统中不easy被用户发觉,能够使用它开发如监控之类的程序. 服务的开发步骤第一步:继承Service类 ...
JavaScript | JQuery插件定义方法
参考 http://www.2cto.com/kf/201507/417874.html ——————————————————————————————————————————————————————— ...
ECMAScript 6 | 新特性
新特性概览参考文章: http://www.cnblogs.com/Wayou/p/es6_new_features.html ——————————————————————————————————— ...
08-spring学习-annotation配置
利用annotation配置注入关系为了更好的解释此类存在的意义,下面通过一段习惯性的开发进行问题的描述,例如: 现在有一个IAdminService服务层,这个服务层要调用的是IAdminDAO和 ...
03-spring学习-自动装配
自动装配新建person类: package com.spring.bean.autowire; public class Person { private String name; private ...
Arrays.sort()
今天在做一个按更新时间搜寻出某个目录里面的全部文件,因为自己写算法比較花费时间,干脆就用j2se提供的类Arrays提供的sort()方法,这样就比較省力.对于基本数据类型仅仅要Arrays.sort ...

swagger在线文档和离线文档

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

随机推荐

热门专题