使用Swagger和SpringFox文件化SpringBootRESTAPI
REST API非常重要。它是一個公共介面，其他模組、應用程式或開發人員需要使用它。擁有適當文件的介面以避免混淆並使其始終保持最新是至關重要的。
最受歡迎的API文件規範之一是OpenApi，以前稱為Swagger。它允許您使用JSON或YAML元資料描述API的屬性。它還提供了一個Web UI，它可以將元資料轉換為一個很好的HTML文件。此外，通過該UI，您不僅可以瀏覽有關API端點的資訊，還可以將UI用作REST客戶端 - 您可以呼叫任何端點，指定要傳送的資料並檢查響應。它非常方便。
手動編寫此類文件並在程式碼更改時保持更新是不現實的。這就是SpringFox發揮作用的地方。它是Spring Framework的Swagger整合。它可以自動檢查您的類，檢測控制器，它們的方法，它們使用的模型類以及它們對映到的URL。沒有任何手寫文件，只需檢查應用程式中的類，它就可以生成大量有關API的資訊。多麼酷啊？最重要的是，每當您進行更改時，它們都會反映在文件中。
新增依賴：
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> <scope>compile</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> <scope>compile</scope> </dependency>
啟用Swagger2:
@SpringBootApplication
@EnableSwagger2
public class ProductApplication {
public static void main(String[] args) {
SpringApplication.run(ProductApplication.class, args);
}
}
Rest控制器：
@RestController
public class ProductController {
@Autowired
private ProductService productService;
@ApiOperation(value = "新增商品", nickname = "createProduct", notes = "備註", tags
= {"商品",})
@ApiResponses(value = {
@ApiResponse(code = 201, message = "建立成功！")})
@PostMapping(value = "/product")
public void createProduct(@ApiParam(value = "新增商品") @Valid @RequestBody
Product body) {
productService.create(body);
}
@PostMapping(value = "/category")
public void createCategory(@RequestBody
Category body) {
//productService.create(body);
}
}
createProduct是有詳細中文說明，createCategory是預設的，兩者顯示API有所不同：
注意，Product作為輸入引數，需要進行API定義，在Idea中有一個SwaggerGen外掛，安裝好後，在Product類中右鍵選擇generate，會有generate swagger選項：
這樣就會為你的模型物件自動生成swagger註解：
@ApiModel(value = "商品", description = "用於實現商品管理")
@Entity
public class Product {
@ApiModelProperty(value = "目錄")
@OneToOne
public Category m_Category;
@ApiModelProperty(value = "標識")
@javax.persistence.Id
private String Id;
@ApiModelProperty(value = "名稱")
private String name;
啟動Spring Boot應用，訪問：
http://localhost:8080/swagger-ui.html
顯示如下：
上面一個“商品”是ProductController的方法createProduct是有詳細中文說明，下面一個顯示“product-controller”是createCategory方法，雖然這個方法沒有任何Swagger2元註釋，但是也自動生成了，名稱直接為REST控制器名稱。
重要的是，填入提交資料，可以類似postman那樣對你的REST API進行資料提交，這樣前端小夥伴再也不抱怨你的API不能用了：
訪問
http://localhost:8080/v2/api-docs
會生成json格式的API說明，能夠匯入前端mock工具供前端除錯程式設計。