有了Swagger2，再也不用為寫Api文件頭疼了

追風人聊Java發表於2021-08-27
SwaggerAPI

1、為什麼要寫Api文件

現在，前後端分離的開發模式已經非常流行，後端開發工程師只負責完成後端介面，前端頁面的開發和渲染完全由前端工程師完成。

問題來了，前端工程師怎麼知道後端介面的具體定義呢？答案是由後端工程師撰寫。

2、寫Api文件很頭疼嗎

答案是一定的，這對後端工程師來說，是額外的工作，編碼已經很耗費精力了，這時前端工程師來催文件，不頭疼才怪：），當然這也不是前端工程師的問題，都是為專案的進度著急。

3、Swagger2

現在好了，一個自動撰寫Api文件的神器出現了，他就是 Swagger2，Swagger2通過美觀的WEB介面展示了所有介面的定義，非常方便，還能直接在介面上進行測試呼叫，有助於除錯。

後端工程師，定義好介面，加幾個註解，便能自動生成線上介面定義，前端工程師可以實時的看到。

下面就來講講如何把 Swagger2 整合到專案中來。

4、介面介紹

這裡以一個簡單的介面作為例子，介面的功能是輸入使用者ID，獲取使用者資料。

5、引入依賴

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

6、增加Swagger2配置類

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

// swagger2配置
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定api型別為swagger2
                    .apiInfo(apiInfo())                 // 用於定義api文件彙總資訊
                    .select()
                    .apis(RequestHandlerSelectors
                            .basePackage("cn.zhuifengren.controller"))   // 指定掃描的controller包
                    .paths(PathSelectors.any())         // 所有controller
                    .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("hello工程介面api")        // 文件頁標題
                .contact(new Contact("hello",
                        "",
                        ""))        // 聯絡人資訊
                .description("專為hello工程提供的api文件")  // 詳細資訊
                .version("1.0.0")   // 文件版本號
                .termsOfServiceUrl("") // 網站地址
                .build();
    }

}

7、在Controller類中增加Swagger2註解

import cn.zhuifengren.model.Result;
import cn.zhuifengren.model.User;
import cn.zhuifengren.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Api(value = "UserController", tags = "使用者介面")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/info/{id}")
    @ApiOperation(value = "獲取使用者資訊")
    public Result<User> getUserInfo(@ApiParam(value = "使用者ID") @PathVariable("id") String id) {

        User userInfo = userService.getUserInfo(id);
        Result<User> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(userInfo);

        return result;
    }

}

其中 @Api註解 放在類上，用於對類的描述，@ApiOperation註解 放在方法上，用於對介面方法的描述。

8、模型類中增加Swagger2註解

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "使用者實體", description = "使用者實體")
public class User {

    @ApiModelProperty(value = "使用者id", name = "id", example = "1")
    private String id;
    @ApiModelProperty(value = "使用者姓名", name = "name", example = "小李")
    private String name;
    @ApiModelProperty(value = "使用者年齡", name = "age", example = "36")
    private Integer age;

其中 @ApiModel註解 放在類上，用於對模型類的描述，@ApiModelProperty註解 放在屬性上，用於對模型屬性的描述。

9、啟動專案檢視效果

啟動專案後，進入地址：http://localhost:8080/swagger-ui.html，即可看到Swagger2 WEB頁面，點選【Try it out】按鈕，還可以對介面進行測試，是不是很方便呢，趕快去用一下吧

 

相關文章