Java | Spring Boot Swagger2 集成REST ful API 生成接口文檔

joyvw 發布于2019-08-16 10:56 / 3224人閱讀

摘要：集成生成接口文檔原文簡介由于的特性，用來開發變得非常容易，并且結合來自動生成文檔變得方便快捷。使用生成，我們可以得到交互式文檔。聽過與的結合，生成更加完備的文檔。接下來將基于與搭建完整的文檔系統。

Spring Boot Swagger2 集成REST ful API 生成接口文檔

原文

簡介

由于Spring Boot 的特性，用來開發 REST ful 變得非常容易，并且結合 Swagger 來自動生成 REST ful API 文檔變得方便快捷。

Swagger 是一個簡單但功能強大的API表達工具。幾乎所有的語言都可以找到與之對應的Swagger 版本。使用Swagger生成API，我們可以得到交互式文檔。聽過Spring Boot 與Swagger 的結合，生成更加完備的REST ful API 文檔。通過在源碼中添加部分內容，系統生成文檔，大大提高工作效率，不用再花費大量時間來創建文檔，同時由于同時是通過代碼開生成文檔，大大降低了維護成本
Swagger 不僅可以組織生成強大的 REST ful 文檔，同時也提供了完備的測試功能，可以直接在文檔頁面測試接口功能。

接下來將基于 Spring Boot 與Swagger 2 搭建完整的API 文檔系統。先來提前目睹下Swagger 生成的文檔樣式

實踐 創建Spring Boot 工程

可以參考前文Spring Boot 初體驗

在POM 文件中添加 Swagger2 包引用

    
        io.springfox
        springfox-swagger2
        2.7.0
    
    
        io.springfox
        springfox-swagger-ui
        2.7.0
    
    
    //導入測試需要的庫 
            
            org.springframework.boot
            spring-boot-starter-data-jpa
        
        
            com.h2database
            h2
            1.4.196
            runtime

本實例采用的是基于內存數據庫H2 的JPA 形式

創建配置類

通過以上方式只能導入 Swagger2 需要的jar包，但當前并不能運行(雖然Spring boot 支持自動化配置)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return  new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.demo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("spring boot , swagger2")
                .termsOfServiceUrl("http:github.com/zhuamaodeyu")
                .contact("抓?的?")
                .version("1.0")
                .build();
    }
}

說明:

@Configuration: 此注解是告訴 Spring Boot 這是一個配置類，需要在項目啟動時加載該類

@EnableSwagger2: Swagger2 是通過此注解來啟動的

通過 api方法創建 Docket 對象，其中主要注意 basePackage配置以及私有方法 apiInfo方法創建的基本信息
通過指定掃描包來配置，以上配置 Swagger 會掃描整個項目工程

創建實體和respository

@Entity
@Table(name="user")
public class User implements Serializable {
//    @ApiModelProperty(notes = "id")
    @Id

    @GeneratedValue(strategy = GenerationType.AUTO)
    private  String id;
    @ApiModelProperty(notes = "uuid")
    private UUID uuid;
    @ApiModelProperty(notes = "用戶名稱")
    private  String name;
    private  String password;
    @ApiModelProperty(notes = "用戶地址")
    private  String address;
    @ApiModelProperty(notes = "年齡")
    private  int age;
    @ApiModelProperty(notes = "郵箱地址")
    private  String email;
    @ApiModelProperty(notes = "描述")
    private  String desc;
    
    // getter/ setter 方法

}

@Repository
public interface UserRepository extends  CrudRepository {

}

測試controller

@RestController
@Api(value = "product 商品操作API")
@RequestMapping("/product")
public class IndexController {

    /**
     * 1. 獲取列表
     * 2. 顯示單個的信息
     * 3. 添加
     * 4. 更新
     * 5. 刪除
     */

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/")
    @ApiOperation(value = "首頁",notes = "測試代碼")
    public  String index()
    {
        return  "index";
    }



    @GetMapping("/list")
    @ApiOperation(value = "獲取全部數據列表", notes = "獲取數據列表")
    public Iterable list(Model model)
    {
        return  userRepository.findAll();
    }

    @GetMapping("/get_user_message")
    @ApiOperation(value = "獲取用戶詳情信息")
    @ApiImplicitParam(name = "userId",value = "用戶ID",defaultValue = "",required = true,dataType = "String")
    public User getUserMessage(String userId)
    {
        return  userRepository.findOne(userId);
    }


    @PostMapping("/save")
    @ApiOperation(value = "保存用戶數據")
    @ApiImplicitParam(name = "user", value = "用戶對象",required = true, dataTypeClass = User.class)
    public String save(@RequestBody User user)
    {
        if (user == null)
        {
            return  "false";
        }

        userRepository.save(user);
        return  "true";
    }

    @PutMapping("/update/{userId}")
    @ApiOperation(value = "更新用戶數據")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用戶的ID", required = true, dataTypeClass = String.class),
            @ApiImplicitParam(name = "user", value = "用戶對象", required = true, dataTypeClass = User.class)
    })

    public ResponseEntity updateUserMessage(@PathVariable String userId, @RequestBody User user)
    {
        User user1 = userRepository.findOne(userId);
        user1.setAddress(user.getAddress());


        userRepository.save(user1);
        return  new ResponseEntity("更新數據成功", HttpStatus.OK);
    }

    @DeleteMapping("/delete/{userId}")
    @ApiOperation(value = "根據用戶ID 刪除用戶數據")
    @ApiImplicitParam(name = "刪除用戶數據",value = "",required = true, dataType = "String")
    public  ResponseEntity deleteUser(@PathVariable String userId)
    {
        userRepository.delete(userId);
        return new ResponseEntity("刪除用戶數據", HttpStatus.OK);
    }
}

測試

實現以上代碼，啟動項目直接訪問http://localhost:8080/swagger-ui.html
就能看到Swagger2 所生成的文檔。可以操作每個請求，其下面是具體的描述和文檔內容

接口調試

Swagger 集成測試
前文提到 Swagger 也提供了接口調試功能，可以直接根據接口要求在圖中標記處填寫接口參數

Postman 測試
通過以上方式可以得到接口文檔，其包含了具體的內容，有了這些內容，就可以通過Postman 等專業的接口測試工具來進行接口的測試

Swagger2 常用配置詳解

@Api

@Api(value="onlinestore", description="當前控制器中的API 的描述信息")

@ApiOperation

此注解是對當前 API 接口的描述，主要是名稱，詳細描述，返回值類型等信息

@ApiOperation(value = "首頁",notes = "測試代碼", tags = {"測試服務是否正常"}, response = String.class)

value : API 的名稱

notes : API 詳細描述信息

response : 返回值類型

tags : 默認的是以類名為標簽的，此處可以自定義標簽

@ApiResponses

@ApiResponse

此注解是對API 返回的結果進行描述

   @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successfully"),
        @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
        @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
        @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
}
)

@ApiImplicitParams

@ApiImplicitParam

這兩個注解是對API 請求參數的描述

@ApiImplicitParams({
        @ApiImplicitParam(name = "userId", value = "用戶的ID", required = true, dataTypeClass = String.class),
        @ApiImplicitParam(name = "user", value = "用戶對象", required = true, dataTypeClass = User.class)
})

@ApiModelProperty
實體類屬性添加描述信息，在接口文檔中可針對類屬性具體含義進行查看

@GeneratedValue(strategy = GenerationType.AUTO)
private  String id;
@ApiModelProperty(notes = "uuid")
private UUID uuid;
@ApiModelProperty(notes = "用戶名稱")
private  String name;
private  String password;
@ApiModelProperty(notes = "用戶地址")
private  String address;
@ApiModelProperty(notes = "年齡")
private  int age;
@ApiModelProperty(notes = "郵箱地址")
private  String email;
@ApiModelProperty(notes = "描述")
private  String desc;

通過以上配置，可以文檔中進行查看

擴展知識 Mock 系統

在現如今的開發中，一個由于項目需求緊，開發周期短，通常涉及到后端以及前端協同工作；一個由于現在大多采用的是前后端分離的開發形式，前后端交互只是通過 REST ful 接口形式來實現的，前后端各自分工工作，所以就存在一個現象就是前端做的快，后端無法及時的給出接口實現并且開發階段沒有數據支撐而造成前端必須等待后端。

現在可以通過先定義接口文檔，生成 Mock 數據的形式來進行前后端分離開發。前端通過調用定義的 Mock 數據來進行前端調試和開發。不需要等待后端的數據

接下來將通過集成 easy-Mock 系統來實現協同開發

easy Mock

easy-mock 是大搜車公司開源的一套 mock 工具，是一個可視化，并且能快速生成模擬數據的持久化服務. 下面將 easy-mock 與 Swagger 結合進行協同工作

搭建easy-mock

下載源碼
easy-mock是一套開源系統，其托管在 github 上,可以通過一下方式獲取源碼
git clone https://github.com/easy-mock/easy-mock.git

修改配置
easy-mock 是使用MongoDB數據的，所以需要配置數據庫
進入 config文件夾，修改 default.json文件

{
      "port": 7300,
      "pageSize": 30,
      "routerPrefix": {
        "mock": "/mock",
        "api": "/api"
      },
      "db": "mongodb://192.168.99.100:32773/easy-mock_",
      "unsplashClientId": "",

修改 db 添加一個可以用的數據庫

啟動
npm run dev
默認的監聽 7300 端口，可以通過localhost:7300訪問系統

導入 Swagger
進入系統創建項目并根據以下方式導入 Swagger

獲取 Swagger 地址

easy-mock創建項目

通過

參考

Easy-Mock

SPRING BOOT RESTFUL API DOCUMENTATION WITH SWAGGER 2

Setting Up Swagger 2 with a Spring REST API

GPU云服務器云服務器生成API文檔 azure java rest api 接口文檔生成工具 Spring Boot

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/70753.html

《 Kotlin + Spring Boot ：下一代 Java 服務端開發》

摘要：下一代服務端開發下一代服務端開發第部門快速開始第章快速開始環境準備，，快速上手實現一個第章企業級服務開發從到語言的缺點發展歷程的缺點為什么是產生的背景解決了哪些問題為什么是的發展歷程容器的配置地獄是什么從到下一代企業級服務開發在移動開發領域《 Kotlin + Spring Boot ：下一代 Java 服務端開發》 Kotlin + Spring Boot ：下一代 Java...

springDevBird 2019-08-15 12:30 評論0 收藏0
SpringBoot 實戰 (五) | 集成 Swagger2 構建強大的 RESTful API

摘要：今天給你們帶來集成的教程。接口返回結果不明確。這些痛點在前后端分離的大型項目上顯得尤為煩躁。接口返回結果非常明確，包括數據類型，狀態碼，錯誤信息等。生成后的文件依賴如下這里使用的是的版本。另外，關注之后在發送可領取免費學習資料。微信公眾號：一個優秀的廢人如有問題或建議，請后臺留言，我會盡力解決你的問題。前言快過年了，不知道你們啥時候放年假，忙不忙。反正我是挺閑的，所以有時間寫 b...

Rindia 2019-08-16 15:12 評論0 收藏0
SpringBoot 2.X Kotlin與Swagger2生成API文檔

摘要：再通過函數創建的之后，用來創建該的基本信息這些基本信息會展現在文檔頁面中。函數返回一個實例用來控制哪些接口暴露給來展現，本例采用指定掃描的包路徑來定義，會掃描該包下所有定義的，并產生文檔內容除了被指定的請求。 showImg(http://download.qfeoo.com/kotlin_springboot_logo.png); 這里有個地方需要注意，在測試WebFlux集成Swa...

cyqian 2019-08-16 16:38 評論0 收藏0