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

從網(wǎng)站建設(shè)到定制行業(yè)解決方案，為提供做網(wǎng)站、成都網(wǎng)站制作服務(wù)體系，各種行業(yè)企業(yè)客戶提供網(wǎng)站建設(shè)解決方案，助力業(yè)務(wù)快速發(fā)展。創(chuàng)新互聯(lián)將不斷加快創(chuàng)新步伐，提供優(yōu)質(zhì)的建站服務(wù)。

（一）引言

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

（二）Swagger與SpringBoot的整合

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

（2.1）引入依賴

先需要創(chuàng)建一個Springboot項目，并引入Swagger2的相關(guān)依賴：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

(2.2)創(chuàng)建實體類

因為項目比較簡單，實現(xiàn)User類的增刪改查API接口，因此全部放在一個文件夾之下，創(chuàng)建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)創(chuàng)建Swagger2配置文件

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //創(chuàng)建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中的參數(shù)如下所示：

（2.4）創(chuàng)建Controller，定義API

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

    //創(chuàng)建一個線程安全的map
    static Map users = Collections.synchronizedMap(new HashMap());

    //獲取User列表
    @ApiOperation(value="獲取用戶列表", notes="")
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List getUserList() {
        List r = new ArrayList(users.values());
        return r;
    }
    //根據(jù)用戶id刪除用戶
    @ApiOperation(value = "刪除用戶",notes = "根據(jù)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";
    }
    //創(chuàng)建用戶
    @ApiOperation(value="創(chuàng)建用戶", notes="根據(jù)User對象創(chuàng)建用戶")
    @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";
    }
    //根據(jù)用戶id獲取用戶信息
    @ApiOperation(value="獲取用戶詳細信息", notes="根據(jù)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);
    }
    //根據(jù)指定id更新對象
    @ApiOperation(value="更新用戶詳細信息", notes="根據(jù)url的id來指定更新對象，并根據(jù)傳過來的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注解來給參數(shù)增加說明。注解各個參數(shù)的功能如下：

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

（三）運行項目

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

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

到此，相信大家對“如何使用Swagger與SpringBoot”有了更深的了解，不妨來實際操作一番吧！這里是創(chuàng)新互聯(lián)網(wǎng)站，更多相關(guān)內(nèi)容可以進入相關(guān)頻道進行查詢，關(guān)注我們，繼續(xù)學(xué)習(xí)！