情景簡(jiǎn)述

在開(kāi)發(fā)過(guò)程中,有時(shí)候我們需要不停的測(cè)試接口,自測(cè),或者交由測(cè)試測(cè)試接口,我們需要構(gòu)建一個(gè)文檔,都是單獨(dú)寫(xiě),太麻煩了,現(xiàn)在使用springboot集成swagger2來(lái)構(gòu)建RESTful API文檔,可以在訪問(wèn)接口上,直接添加注釋就能實(shí)現(xiàn)

開(kāi)發(fā)環(huán)境

先介紹一下開(kāi)發(fā)環(huán)境:

• jdk版本是1.8
• springboot的版本是1.4.1
• 開(kāi)發(fā)工具為 intellij idea

我們先引入swagger2的jar包,pom文件引入依賴(lài)如下:

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

使用實(shí)例

接下來(lái),我們構(gòu)建swagger2的配置類(lèi),代碼如下:

//注解開(kāi)啟 swagger2 功能
@EnableSwagger2
//注解標(biāo)示,這是一個(gè)配置類(lèi),@Configuation注解包含了@Component注解
//可以不用在使用@Component注解標(biāo)記這是個(gè)bean了,
@Configuration
public class Swagger2 {

    /**
     * 通過(guò) createRestApi函數(shù)來(lái)構(gòu)建一個(gè)DocketBean
     * 函數(shù)名,可以隨意命名,喜歡什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())//調(diào)用apiInfo方法,創(chuàng)建一個(gè)ApiInfo實(shí)例,里面是展示在文檔頁(yè)面信息內(nèi)容
                .select()
                //控制暴露出去的路徑下的實(shí)例
                //如果某個(gè)接口不想暴露,可以使用以下注解
                //@ApiIgnore 這樣,該接口就不會(huì)暴露在 swagger2 的頁(yè)面下
                .apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
    //構(gòu)建 api文檔的詳細(xì)信息函數(shù)
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁(yè)面標(biāo)題
                .title("Spring Boot 測(cè)試使用 Swagger2 構(gòu)建RESTful API")
                //創(chuàng)建人
                .contact("賀小五")
                //版本號(hào)
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}
 
swagger2的配置類(lèi)已經(jīng)配置好了,下面,我們就在主函數(shù)里面隨意寫(xiě)一些接口吧
 
@SpringBootApplication(scanBasePackages = {"com"})
//該注解包含了@Controller和@ResponseBody兩個(gè)注解
@RestController
public class DemoApplication{

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    /**
    * 以下函數(shù)的注釋,不增加注解了,將在下面統(tǒng)一做描述
    */


    @ApiOperation(value = "測(cè)試post請(qǐng)求",notes="注意事項(xiàng)")
    @ApiImplicitParam(dataType = "User",name = "user",value = "用戶(hù)信息",required = true)
    @RequestMapping(value = "/testPost",method = RequestMethod.POST)
    public String testPost(@RequestBody User user){
        return "success";
    }


    @ApiOperation(value = "測(cè)試get請(qǐng)求",notes="注意事項(xiàng)")
    @ApiImplicitParam(name = "id",value = "用戶(hù)id",dataType = "String",paramType = "path")
    @RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET)
    public String testGet(@PathVariable String id){
        return id;
    }

    @ApiOperation(value = "測(cè)試組合注解",notes="注意事項(xiàng)")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "User",name = "user",value = "用戶(hù)信息",required = true,paramType = "body"),
            @ApiImplicitParam(dataType = "string",name = "id",value = "用戶(hù)id",required = true,paramType = "path")
    })
    @RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST)
    public User joinAnnotation(@PathVariable String id,@RequestBody User user){
        return user;
    }
    
    @ApiIgnore
    public String testIgnore(){
        return "success";
    }
}

寫(xiě)好controller后,我們可以訪問(wèn)以下地址:http://localhost:8080/swagger-ui.html,如果你沒(méi)引入swagger2依賴(lài),你是訪問(wèn)不了的..然后你會(huì)得到一個(gè)如下頁(yè)面

image.png

上面的頁(yè)面,就是swagger2里面的頁(yè)面,可以發(fā)現(xiàn), apiInfo里面設(shè)置的內(nèi)容在左邊展示出來(lái)了,demo-application其實(shí)就是controller的類(lèi)名,右邊有三個(gè)按鈕,分別是 Show/Hide,List Opertions和Expand Operations,三個(gè)按鈕都可以打開(kāi),類(lèi)下的接口,點(diǎn)擊后,會(huì)得到如下一個(gè)效果頁(yè)面:

image.png

可以發(fā)現(xiàn),展示出來(lái)了,controller下的三個(gè)接口(其實(shí)有四個(gè),只不過(guò)有一個(gè)我們用注解忽略了,在這不展示而已..)

上面三個(gè)接口,在我們注解里面添加的,都有展示,請(qǐng)求方式,接口名稱(chēng),現(xiàn)在我們打開(kāi)某個(gè)接口,看看具體內(nèi)容,接口內(nèi)的內(nèi)容,我不在用文字描述,我直接在截圖里面添加描述了.見(jiàn)諒....

image.png

image.png

我們點(diǎn)擊try it out 按鈕,就會(huì)發(fā)送請(qǐng)求,結(jié)果如下:

image.png

swagger官網(wǎng)地址:http://swagger.io/

重要參數(shù)

下面就是介紹,上面接口中,上面關(guān)于swagger2本人常用注解的一些描述

本人常用注解說(shuō)明：

@ApiOperation：用在方法上，說(shuō)明方法的作用

value: 表示接口名稱(chēng)
notes: 表示接口詳細(xì)描述 

@ApiImplicitParams：用在方法上包含一組參數(shù)說(shuō)明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面

paramType：參數(shù)位置
header 對(duì)應(yīng)注解：@RequestHeader
query 對(duì)應(yīng)注解：@RequestParam
path 對(duì)應(yīng)注解: @PathVariable
body 對(duì)應(yīng)注解: @RequestBody
name：參數(shù)名
dataType：參數(shù)類(lèi)型
required：參數(shù)是否必須傳
value：參數(shù)的描述
defaultValue：參數(shù)的默認(rèn)值
@ApiResponses：用于表示一組響應(yīng)

@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息

code：狀態(tài)碼
message：返回自定義信息
response：拋出異常的類(lèi)
@ApiIgnore: 表示該接口函數(shù)不對(duì)swagger2開(kāi)放展示

注意事項(xiàng)

以上這些就是我測(cè)試過(guò)的注解,并沒(méi)有深究,有興趣的,可以看看其它注解,或者源碼,會(huì)比我描述的全很多,

對(duì)了,需要注意下,@ApiImplicitParam注解下的paramType屬性,會(huì)影響接口的測(cè)試,如果設(shè)置的屬性跟spring的注解對(duì)應(yīng)不上,會(huì)獲取不到參數(shù),例如:paramType=path,函數(shù)內(nèi)卻使用@RequestParam注解,這樣,可能會(huì)獲取不到傳遞進(jìn)來(lái)的參數(shù),需要按照上面進(jìn)行對(duì)應(yīng),將@RequestParam注解改為@PathVariable才能獲取到對(duì)應(yīng)的參數(shù)...