溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
這篇文章主要介紹“java集成開發SpringBoot生成接口文檔的方法是什么”，在日常操作中，相信很多人在java集成開發SpringBoot生成接口文檔的方法是什么問題上存在疑惑，小編查閱了各式資料，整理出簡單好用的操作方法，希望對大家解答”java集成開發SpringBoot生成接口文檔的方法是什么”的疑惑有所幫助！接下來，請跟著小編一起來學習吧！
作為一名程序員，我們最討厭兩件事：1. 別人不寫注釋。2. 自己寫注釋。
而作為一名接口開發者，我們同樣討厭兩件事：
1. 別人不寫接口文檔，文檔不及時更新。
2. 需要自己寫接口文檔，還需要及時更新。
相信無論是前端還是后端開發，都或多或少地被接口文檔折磨過。前端經常抱怨后端給的接口文檔與實際情況不一致。后端又覺得編寫及維護接口文檔會耗費不少精力，經常來不及更新。
而隨著Springboot、Springcloud等微服務的流行，每個項目都有成百上千個接口調用，這時候再要求人工編寫接口文檔并且保證文檔的實時更新幾乎是一件不可能完成的事，所以這時候我們迫切需要一個工具，一個能幫我們自動化生成接口文檔以及自動更新文檔的工具。它就是Swagger。
Swagger 提供了一個全新的維護 API 文檔的方式，有4大優點：
自動生成文檔：只需要少量的注解，Swagger 就可以根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。
跨語言性，支持 40 多種語言。
Swagger UI 呈現出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備復雜的調用參數的過程。
還可以將文檔規范導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創建自動化測試。
現在我們知道了Swagger的作用，接下來將其集成到我們項目中。
集成Swagger很簡單，只需要簡單三步。
<!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!--swagger-ui--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
application.properties 加入配置
# 用于控制是否開啟Swagger，生產環境記得關閉Swagger，將值設置為 false springfox.swagger2.enabled = true
增加一個swagger配置類
@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
public class SwaggerConfig {
private static final String VERSION = "1.0";
@Value("${springfox.swagger2.enabled}")
private Boolean swaggerEnabled;
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.enable(swaggerEnabled)
.groupName("SwaggerDemo")
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("接口文檔")
.contact(new Contact("JAVA日知錄","http://javadaily.cn","jianzh6@163.com"))
.description("Swagger接口文檔")
.version(VERSION)
.build();
}
}這里通過 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
表面給加上 @Api注解的類自動生成接口文檔。
@RestController
@Api(tags = "參數校驗")
@Slf4j
@Validated
public class ValidController {
@PostMapping("/valid/test1")
@ApiOperation("RequestBody校驗")
public String test1(@Validated @RequestBody ValidVO validVO){
log.info("validEntity is {}", validVO);
return "test1 valid success";
}
@ApiOperation("Form校驗")
@PostMapping(value = "/valid/test2")
public String test2(@Validated ValidVO validVO){
log.info("validEntity is {}", validVO);
return "test2 valid success";
}
@ApiOperation("單參數校驗")
@PostMapping(value = "/valid/test3")
public String test3(@Email String email){
log.info("email is {}", email);
return "email valid success";
}
}通過 @Api注解標注需要生成接口文檔，通過 @ApiOperation注解標注接口名。
同時我們給 ValidVO也加上對應的注解
@Data
@ApiModel(value = "參數校驗類")
public class ValidVO {
@ApiModelProperty("ID")
private String id;
@ApiModelProperty(value = "應用ID",example = "cloud")
private String appId;
@NotEmpty(message = "級別不能為空")
@ApiModelProperty(value = "級別")
private String level;
@ApiModelProperty(value = "年齡")
private int age;
...
}通過 @ApiModel標注這是一個參數實體，通過 @ApiModelProperty標注字段說明。
簡單三步，我們項目就集成了Swagger接口文檔，趕緊啟動服務，訪問 http://localhost:8080/swagger-ui.html 體驗一下。
好吧，出了點小問題，不過不用慌。
出現這個問題的原因是因為我們加上了 ResponseBodyAdvice統一處理返回值/響應體，導致給Swagger的返回值也包裝了一層，UI頁面無法解析。可以通過 http://localhost:8080/v2/api-docs?group=SwaggerDemo觀察Swagger返回的json數據。
既然知道了問題原因那就很好解決了，我們只需要在ResponseBodyAdvice處理類中只轉換我們自己項目的接口即可。
@RestControllerAdvice(basePackages = "com.jianzh6.blog")
@Slf4j
public class ResponseAdvice implements ResponseBodyAdvice<Object> {
...
}通過添加basePackage屬性限定統一返回值的范圍，這樣就不影響Swagger了。
重啟服務器再次訪問swagger接口地址，就可以看到接口文檔頁面了。
Swagger2.9.2有個bug，就是當我們參數實體有int類型的參數時，打開Swagger接口頁面時后端會一直提示異常：
java.lang.NumberFormatException: For input string: "" at java.base/java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) at java.base/java.lang.Long.parseLong(Long.java:702) at java.base/java.lang.Long.valueOf(Long.java:1144)
有兩種解決方案：
給int類型的字段使用@ApiModelPorperty注解時添加example屬性
@ApiModelProperty(value = "年齡",example = "10") private int age;
去除原swagger中的swagger-models和swagger-annotations，自行引入高版本的annotations和models
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> </exclusion> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>1.5.22</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.22</version> </dependency>
集成Swagger過程中雖然會出現兩個小問題，解決后我們就可以愉快享受Swagger給我們帶來的便利了。
Swagger原生UI有點丑，我們可以借助Swagger的增強工具 knife4j優化一下。
<!--整合Knife4j--> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.4</version> </dependency>
由于knife4j中已經帶了 swagger-annotations和 swagger-models的依賴，所以我們可以把上文中手動添加的兩個依賴刪除。
@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
@EnableKnife4j
public class SwaggerConfig {
...
}通過上面兩步我們就完成了Swagger的美化，通過瀏覽器訪問 http://localhost:8080/doc.html 即可看到效果。
看到這里的同學心理肯定會想，就這？這就是老鳥的做法？跟我們新手也沒啥區別呀
別急，我們先來看一個效果。
首先我們定義了兩個接口，一個新增，一個編輯
@ApiOperation("新增")
@PostMapping(value = "/valid/add")
public String add(@Validated(value = {ValidGroup.Crud.Create.class}) ValidVO validVO){
log.info("validEntity is {}", validVO);
return "test3 valid success";
}
@ApiOperation("更新")
@PostMapping(value = "/valid/update")
public String update(@Validated(value = ValidGroup.Crud.Update.class) ValidVO validVO){
log.info("validEntity is {}", validVO);
return "test4 valid success";
}注意看，這里用的是同一個實體 ValidVO來接收前端參數，只不過使用了參數校驗中的分組，然后我們打開kife4j頁面觀察兩者的接口文檔有何不同。
新增：
編輯：
通過上面可以看到，雖然用于接受參數的實體一樣，但是當分組不一樣時展示給前端的參數也不一樣，這就是Swagger的分組功能。
當然原生的Swagger是不支持分組功能的，我們需要對Swagger進行擴展。我已經將代碼上傳到了github上，由于代碼量比較多這里就不展示了，大家可以自行查閱。
引入擴展類后還需要在Swagger配置類 SwaggerConfig中注入對應的Bean。
@Configuration
@EnableSwagger2
@ConditionalOnClass(Docket.class)
@EnableKnife4j
public class SwaggerConfig {
...
@Bean
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupOperationModelsProviderPlugin groupOperationModelsProviderPlugin() {
return new GroupOperationModelsProviderPlugin();
}
@Bean
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupModelBuilderPlugin groupModelBuilderPlugin() {
return new GroupModelBuilderPlugin();
}
@Bean
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupModelPropertyBuilderPlugin groupModelPropertyBuilderPlugin() {
return new GroupModelPropertyBuilderPlugin();
}
@Bean
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupExpandedParameterBuilderPlugin groupExpandedParameterBuilderPlugin() {
return new GroupExpandedParameterBuilderPlugin();
}
@Bean
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupOperationBuilderPlugin groupOperationBuilderPlugin() {
return new GroupOperationBuilderPlugin();
}
@Bean
@Primary
@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER + 1000)
public GroupModelAttributeParameterExpander groupModelAttributeParameterExpander(FieldProvider fields, AccessorsProvider accessors, EnumTypeDeterminer enumTypeDeterminer) {
return new GroupModelAttributeParameterExpander(fields, accessors, enumTypeDeterminer);
}
}@Null(groups = ValidGroup.Crud.Create.class) @NotNull(groups = ValidGroup.Crud.Update.class,message = "應用ID不能為空") @ApiModelProperty(value = "應用ID",example = "cloud") private String appId;
當新增場景的時候，appId為空，不需要傳值； 當修改場景的時候，appId不能為空，需要傳值 ；其他沒有配置組的皆為默認組(Default)
@ApiOperation("新增")
@PostMapping(value = "/valid/add")
public String add(@Validated(value = {ValidGroup.Crud.Create.class}) ValidVO validVO){
log.info("validEntity is {}", validVO);
return "test3 valid success";
}當前接口會針對默認組的bean屬性進行校驗，同時針對保存常見的屬性進行校驗。
到此，關于“java集成開發SpringBoot生成接口文檔的方法是什么”的學習就結束了，希望能夠解決大家的疑惑。理論與實踐的搭配能更好的幫助大家學習，快去試試吧！若想繼續學習更多相關知識，請繼續關注億速云網站，小編會繼續努力為大家帶來更多實用的文章！
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
