springboot2.0 swagger2 生成離線文件
阿新 • • 發佈:2018-12-15
前面寫了springboot swagger2生成線上文件,應公司要求,還必須生成離線文件,兩個相結合,這個為什麼要自動生成文件的緣由就不說了,想必大家心裡都清楚
maven依賴
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.5.RELEASE</version> </parent> <properties> <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </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>org.projectlombok</groupId> <artifactId>lombok</artifactId> <version>1.16.10</version> </dependency> <dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.8</version> </dependency> </dependencies> <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}/docs/asciidoc</sourceDirectory> <sourceDocumentName>index.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>
程式碼部分
index.adoc檔案
新建檔案及目錄結構 src/docs/asciidoc/index.adoc 內容如下
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
swagger配置
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();
}
}
controller
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;
}
test 目錄下的Documentation類
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必須和外掛裡面<generated></generated>標籤配置一致
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修改一點點