前面写了springboot swagger2生成在线文档,应公司要求,还必须生成离线文档,两个相结合,这个为什么要自动生成文档的缘由就不说了,想必大家心里都清楚
org.springframework.boot
spring-boot-starter-parent
2.0.5.RELEASE
${project.build.directory}/generated-snippets
org.springframework.boot
spring-boot-starter-web
org.springframework.boot
spring-boot-starter-test
io.springfox
springfox-swagger2
2.6.1
io.springfox
springfox-swagger-ui
2.6.1
org.springframework.restdocs
spring-restdocs-mockmvc
test
io.springfox
springfox-staticdocs
2.6.1
org.projectlombok
lombok
1.16.10
com.alibaba
fastjson
1.2.8
org.springframework.boot
spring-boot-maven-plugin
org.apache.maven.plugins
maven-surefire-plugin
**/*Documentation.java
新建文件及目录结构 src/docs/asciidoc/index.adoc
内容如下
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
import springfox.documentation.service.Contact;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 自己controller 路径
.apis(RequestHandlerSelectors.basePackage("com.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("api 接口")
.description("rest服务说明")
.version("2.0").contact(new Contact("liu", "url", "[email protected]")).build();
}
}
import com.chinamobile.iot.model.Student;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api("HelloController 相关接口说明")
@ApiResponses({
@ApiResponse(code = 200, message = "OK"),
@ApiResponse(code = 400, message = "客户端请求错误"),
@ApiResponse(code = 404, message = "找不到路径"),
@ApiResponse(code = 500, message = "编译异常")
})
public class HelloController {
@ApiOperation(value = "查询某个设备信息", notes = "查询某个设备信息 1")
@GetMapping("/getDevice/{id}")
public String getDevice(@ApiParam(name = "id", value = "设备的唯一编号", required = true) @PathVariable int id,
@RequestBody Student student) {
return "hello swagger2: "+ id;
}
}
这个只是一个使用案例,还有很多注解
注意 @RequestBody Student student 纯粹是为了看实体类的效果加的,打包后在definitions.adoc文件中,当然了,还有其他方式,这只是一种
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@ApiModel(value = "Student", description = "学生信息描述")
@Data
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;
}
import io.github.robwin.markup.builder.MarkupLanguage;
import io.github.robwin.swagger2markup.GroupBy;
import io.github.robwin.swagger2markup.Swagger2MarkupConverter;
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.RestDocumentationRequestBuilders;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.MockMvc;
import springfox.documentation.staticdocs.SwaggerResultHandler;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class Documentation {
private String snippetDir = "target/generated-snippets";
private String outputDir = "target/asciidoc";
//private String indexDoc = "docs/asciidoc/index.adoc";
@Autowired
private MockMvc mockMvc;
@After
public void test() throws Exception{
// 得到swagger.json,写入outputDir目录中
mockMvc.perform(RestDocumentationRequestBuilders.get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
.andExpect(status().isOk())
.andReturn();
// 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
// 这个outputDir必须和插件里面 标签配置一致
Swagger2MarkupConverter.from(outputDir + "/swagger.json")
.withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
.withExamples(snippetDir)
.build()
.intoFolder(outputDir);// 输出
}
@Test
public void testApi() throws Exception{
}
}
打包即可
打包完成在target/asciidoc目录下就可以看文档
参考 https://www.jianshu.com/p/af7a6f29bf4f
注意,该博主的springboot版本是1.4.0的,如若用现在最新的2.0.5会报错,得把pom.xml修改一点点