1.springboot版本：
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
2.导入swagger相关的依赖：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.5</version>
</dependency>
<!-- swagger的依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
3.API
package com.example.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.List;
/**
* 蓝色界面
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* @Description 构建API基本信息
* @Param []
* @return springfox.documentation.service.ApiInfo
**/
private ApiInfo buildApiInfo() {
return new ApiInfoBuilder()
.title("接口说明文档")
.description("说明文档简介")
.contact("sunrj")
.version("1.0")
.build();
}
@Bean
public Docket docket() {
/*
* 全局配置信息（可以不用）例如：token
*/
Parameter token = new ParameterBuilder().name("token")
.description("用户令牌")
.parameterType("header")
.modelRef(new ModelRef("String"))
.build();
List<Parameter> parameters = new ArrayList<>();
parameters.add(token);
return new Docket(DocumentationType.SWAGGER_2)
.globalOperationParameters(parameters) //传入全局配置
.apiInfo(buildApiInfo()) //传入api首页信息
.select() //进行筛选
//通过package筛选，
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
//构建api
.build();
}
}
3.controller
这里swagger的参数不做任何介绍，具体参数意思的大家自行百度
@RestController
@RequestMapping(value = "user", produces = MediaType.APPLICATION_JSON_VALUE)
@Api(value = "用户信息管理", tags ={"UserController"}, description = "用户基本信息操作API", consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController {
@Autowired
private UserService userService;
@Ignore
@RequestMapping(value = "loginUser",method = RequestMethod.POST )
@ApiOperation(value = "/loginUser", notes="通过用户名密码验证是否登陆成功")
//@ApiImplicitParam(paramType="query", name = "user", value = "登录的用户名和密码信息", required = true, dataType = "User")
public ResponseServer loginUser(User user){
return userService.loginUser(user);
}
/**
* 查询当前用户拥有的问卷调查列表
* @return
*/
//@RequestMapping("queryUserSurveyList")
@RequestMapping(value = "queryUserSurveyList",method = RequestMethod.POST )
@ApiOperation(value = "/queryUserSurveyList", notes="查询当前用户拥有的问卷调查列表")
public ResponseServer queryUserSurveyList(User userSel){
return userService.queryUserSurveyList(userSel.getName());
}
@RequestMapping(value = "queryUserAll",method = RequestMethod.GET )
@ApiOperation(value = "/queryUserAll", notes="查询所有用户")
public ResponseServer queryUserAll(){
return userService.queryUserAll();
}
@RequestMapping(value = "insertUser",method =RequestMethod.POST )
@ApiOperation(value = "/insertUser", notes="增加用户")
public ResponseServer insertUser(@RequestBody User user){
return userService.insertUser(user);
}
@ApiOperation(value = "/deleteUser", notes="通过id删除用户信息")
@RequestMapping(value = "deleteUser",method =RequestMethod.DELETE )
@ApiImplicitParam(paramType="query", name = "userId", value = "删除的用户Id", required = true, dataType = "int")
public ResponseServer deleteUser( Integer userId){
return userService.deleteUser(userId);
}
@ApiOperation(value = "/updateUser", notes="通过id修改用户信息")
@RequestMapping(value = "updateUser",method =RequestMethod.PUT )
public ResponseServer updateUser(@RequestBody User user){
return userService.updateUser(user);
}
}
4.model
package com.example.model;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.annotations.ApiModel;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@ApiModel(value="User", description = "用户的实体对象")
@AllArgsConstructor
@NoArgsConstructor
@Data
@TableName("t_user")
public class User {
//@ApiModelProperty(value="userId" ,required=false)
@TableId(value = "user_id", type = IdType.AUTO)
@TableField(value = "user_id", exist = true)
private Integer userId;
// @ApiModelProperty(value="name" ,required=false)
@TableField(value = "user_name", exist = true)
private String name;
// @ApiModelProperty(value="password" ,required=false)
@TableField(value = "user_password", exist = true)
private String password;
}
然后就成功了，启动程序：
访问：
http://localhost:8080/doc.html
成功：
还有另外一种页面，这里swagger的管理UI页面的依赖需要改成这个：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
访问路径：
http://localhost:8088/swagger-ui.html
就可以了
其实很简单，就是修改测试类，和配置文件
1.测试类
package com.example;
import static org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
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 io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.GroupBy;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
import springfox.documentation.staticdocs.SwaggerResultHandler;
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class WeikangDemoApplicationTests {
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("/v2/api-docs").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);// 输出
}
/**
*
* Description: 一定要有测试方法，调用方法不限制
*
* @param
* @return void
* @throws
* @Author lkf
* Create Date: 2020年9月27日 下午4:46:11
*/
@Test
public void TestApi() throws Exception {
mockMvc.perform(get("/user/queryUserAll").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andDo(MockMvcRestDocumentation.document("queryUserAll", preprocessResponse(prettyPrint())));
}
}
2.配置文件
<properties>
<java.version>1.8</java.version>
<!--swgger2markup 配置信息-->
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
</properties>
<!--离线文档-->
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-mockmvc</artifactId>
<scope>test</scope>
</dependency>
<!--springfox-staticdocs 生成静态文档-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-staticdocs</artifactId>
<version>2.6.1</version>
<scope>test</scope>
</dependency>
<build>
<finalName>springboot_swagger</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<!--<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>-->
<!--Maven通过Maven Surefire Plugin插件执行单元测试-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<testFailureIgnore>true</testFailureIgnore>
</configuration>
</plugin>
<!--通过Asciidoctor使得asciidoc生成其他的文档格式，例如：PDF 或者HTML5-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<!--生成PDF-->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.14</version>
</dependency>
<!-- Comment this section to use the default jruby artifact provided by the plugin -->
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<!--文档生成配置-->
<configuration>
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
</configuration>
<!--因为每次执行只能处理一个后端，所以对于每个想要的输出类型，都是独立分开执行-->
<executions>
<!--html5-->
<execution>
<id>output-html</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
</configuration>
</execution>
<!--pdf-->
<execution>
<id>output-pdf</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
<!--解决中文乱码以及中文丢失问题-->
<attributes>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
<pdf-fontsdir>fonts</pdf-fontsdir>
<pdf-stylesdir>themes</pdf-stylesdir>
<pdf-style>cn</pdf-style>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
我这里上springboot 2.1.3.RELEASE的版本
解决方案：
一种是下载字体（RobotoMono 开头和 KaiGenGothicCN 开头的字体文件）和theme文件（Source code (zip)）。
字体下载链接：https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases
然后在项目的资源目录下创建fonts和themes两个目录，把下载的8个字体文件复制到fonts目录下，解压asciidoctor-pdf-cjk-kai_gen_gothic-0.1.0-fonts.zip文件，把data\themes\下的cn-theme.yml复制到themes目录下
pom.xml配置，
如图：
这样就可以解决，网上还有别的方式。大家可以按照自己的版本解决
执行：
1.先执行测试类
2.命令 mvn clean test
然后就生成了：
具体需要什么文档，大家按需求进行配置即可
