專案基礎

springboot 2.02
springfox-swagger2/springfox-swagger-ui 2.8
io.github.swagger2markup 1.3.3

在需要加入的專案RESTful API HTML文件引入依賴

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

在springboot 啟動 Application同級建立一個swagger2配置檔案

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("你的需要生成文件的包位置"))
                .paths(PathSelectors.any())
                .build();
    }


}
 

加入文件註解

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class AreaDto implements Serializable {
    @ApiParam(value = "區域名", required = true)
    private String name;
}

@RestController
@RequestMapping(value="/pc/area")
public class AreaController {

    @GetMapping(value="/")
    @ApiOperation("獲取區域列表")
    public Result<AreaDto> getAreaList() {
        return Result.<AreaDto>builder().build();
    }

    @PostMapping(value="/")
    @ApiOperation("新增一個區域")
    @ApiImplicitParam(name = "area", value = "區域實體DTO", required = true, dataType = "AreaDto")
    public Result<String> postUser(@ModelAttribute AreaDto area) {
        return  Result.<String>builder().success(true).build();
    }

    @PutMapping(value="/{id}")
    @ApiOperation("根據ID更新一個區域的資訊")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "區域ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "area", value = "區域DTO", required = true, dataType = "AreaDto")
    })
    public Result<String> putUser(@PathVariable Long id, @ModelAttribute AreaDto area) {
        return  Result.<String>builder().success(false).errorCode(ErrorCode.USER_NOT_FOUND).build();
    }

    @DeleteMapping(value="/{id}")
    @ApiOperation("根據ID刪除一個區域")
    @ApiImplicitParam(name = "id", value = "區域id", required = true, dataType = "Long")
    public Result<String> deleteUser(@PathVariable Long id) {
        return  Result.<String>builder().success(true).successCode(SuccessCode.FORWARDING).build();
    }
}

接下來是生成離線PDF、HTML、ADOC的步驟，不需要可以跳過

開啟專案，修改POM檔案

把swagger.input修改成年上面儲存的json資料

進行編譯

mvn test或者用idea的工具進行編譯，開啟編譯後的目錄，可以發現我們需要的檔案已經
生成

檢視PDF，如果發現亂碼，請繼續往下看

安裝完成後，通過該軟體開啟ADOC，然後點選右上角轉存為PDF，可以發現已經沒有亂碼，如果需要轉換DOC，可以藉助其他工具（如Adobe Acrobat Reader）

總結

在轉換成ＰＤＦ過程出現亂碼、檔案丟失等現象，可能是配置中出了問題，對於我來說文件只需要生成一次，因此選擇了最節省時間的一種方案，有興趣的朋友可以看下https://github.com/Swagger2Markup/swagger2markup。