如何使用Swagger與SpringBoot

本篇內容主要講解“如何使用Swagger與SpringBoot”，感興趣的朋友不妨來看看。本文介紹的方法操作簡單快捷，實用性強。下面就讓小編來帶大家學習“如何使用Swagger與SpringBoot”吧!

（一）引言

我的第一份工作用的技術架構比較老，在寫Api接口的時候都是自己手動寫一個接口文檔。但是一旦接口多了，這些文檔就很難管理。我現在的工作在應用層面使用了SpringBoot，項目中也大量用到了Swagger2。我個人感覺Swagger的厲害之處在于極少的配置和幾個注解就可以生成一份完善的技術文檔，將維護文檔和修改代碼整合為一體，節省了大量時間。

（二）Swagger與SpringBoot的整合

Swagger的使用很簡單，這里通過一個簡單的例子進行展示

（2.1）引入依賴

先需要創建一個Springboot項目，并引入Swagger2的相關依賴：

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

(2.2)創建實體類

因為項目比較簡單，實現User類的增刪改查API接口，因此全部放在一個文件夾之下，創建User.java，這里用到了swagger對于實體類的兩個注解@ApiModel和@ApiModelProperty，分別表示實體類的含義以及屬性的含義。

@Data
@ApiModel("用戶實體類")
public class User {
    @ApiModelProperty("id")
    private Long id;
    @ApiModelProperty("name")
    private String name;
    @ApiModelProperty("age")
    private Integer age;
}

(2.3)創建Swagger2配置文件

swagger的配置主要基本的展示信息以及掃描信息，其中@Configuration注解使得Spring啟動該配置類，@EnableSwagger2啟動Swagger2

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //創建api基本信息
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors.basePackage指定掃描的包路徑
                //RequestHandlerSelectors.any():掃描全部
                //RequestHandlerSelectors.none():不掃描
                //RequestHandlerSelectors.withClassAnnotation():掃描類上的注解
                //RequestHandlerSelectors.withMethodAnnotation():掃描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.javayz.swaggerdemo.controller"))
                //過濾什么路徑
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Java魚仔的SwaggerAPI文檔")
                .description("你會累因為你在走上坡路")
                .termsOfServiceUrl("https://blog.csdn.net/qq_41973594")
                .contact(new Contact("Java魚仔","https://blog.csdn.net/qq_41973594","974474148@qq.com"))
                .version("1.0")
                .build();
    }
}

ApiInfo中的參數如下所示：

（2.4）創建Controller，定義API

@Api(value = "用戶信息管理")
@RestController
@RequestMapping(value="/users")
public class UserController {

    //創建一個線程安全的map
    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    //獲取User列表
    @ApiOperation(value="獲取用戶列表", notes="")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }
    //根據用戶id刪除用戶
    @ApiOperation(value = "刪除用戶",notes = "根據id刪除用戶")
    @ApiImplicitParam(name = "id",value = "輸入用戶id",required = true,dataType = "Long")
    @RequestMapping(value = "/{id}",method = RequestMethod.DELETE)
    public String DeleteList(@PathVariable Long id){
        users.remove(id);
        return "success";
    }
    //創建用戶
    @ApiOperation(value="創建用戶", notes="根據User對象創建用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "success";
    }
    //根據用戶id獲取用戶信息
    @ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }
    //根據指定id更新對象
    @ApiOperation(value="更新用戶詳細信息", notes="根據url的id來指定更新對象，并根據傳過來的user信息來更新用戶詳細信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "success";
    }
}

以上代碼乍一看有很多的配置文件，其實實際使用起來很簡單，通過@Api、@ApiOperation注解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam注解來給參數增加說明。注解各個參數的功能如下：

@Api：用在請求的類上，表示對類的說明
    tags="說明該類的作用，可以在UI界面上看到的注解"
    value="該參數沒什么意義，在UI界面上也看到，所以不需要配置"
 
@ApiOperation：用在請求的方法上，說明方法的用途、作用
    value="說明方法的用途、作用"
    notes="方法的備注說明"
 
@ApiImplicitParams：用在請求的方法上，表示一組參數說明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數的各個方面
        name：參數名
        value：參數的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪個地方
            · header --> 請求參數的獲?。篅RequestHeader
            · query --> 請求參數的獲?。篅RequestParam
            · path（用于restful接口）--> 請求參數的獲?。篅PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：參數類型，默認String，其它值dataType="Integer"       
        defaultValue：參數的默認值
        
@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息
        code：數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類
 
@ApiModel：用于響應類上，表示一個返回響應數據的信息
            （這種一般用在post創建的時候，使用@RequestBody這樣的場景，
            請求參數無法使用@ApiImplicitParam注解進行描述的時候）
    @ApiModelProperty：用在屬性上，描述響應類的屬性

（三）運行項目

完成全部代碼之后，啟動SpringBoot項目，在瀏覽器上輸入 http://localhost:8080/swagger-ui.html ，就能看到RESTful API接口界面

這個界面中可以直接測試接口，每次代碼修改也都會同步到接口文檔中。我們只需要把這個路徑發給前端同學就大功告成了。

到此，相信大家對“如何使用Swagger與SpringBoot”有了更深的了解，不妨來實際操作一番吧！這里是億速云網站，更多相關內容可以進入相關頻道進行查詢，關注我們，繼續學習！