swagger2:兩分鐘學(xué)會(huì)swagger

學(xué)習(xí)背景

或許我們習(xí)慣用postman調(diào)試接口杉允,但是你會(huì)發(fā)現(xiàn)赘娄,每次調(diào)試一個(gè)接口時(shí)都需要把路徑和參數(shù)寫上去,有的時(shí)候還容易寫錯(cuò)故响,大大耽誤了咱們的開發(fā)時(shí)間。

swagger是什么東西颁独?

swagger用于定義API文檔彩届。

優(yōu)點(diǎn)

  • 前后端分離開發(fā)
  • API文檔非常明確
  • 測(cè)試的時(shí)候不需要再使用URL輸入瀏覽器的方式來訪問Controller
    傳統(tǒng)的輸入U(xiǎn)RL的測(cè)試方式對(duì)于post請(qǐng)求的傳參比較麻煩(當(dāng)然,可以使用postman這樣的瀏覽器插件)
  • spring-boot與swagger的集成簡(jiǎn)單的一b

實(shí)踐

  • 項(xiàng)目前準(zhǔn)備一個(gè)maven+spring boot項(xiàng)目(自己去ij IDE上自動(dòng)生成一個(gè))
第一步:

在maven 中加入下面?zhèn)z個(gè)依賴誓酒,一定是2.6.1之后的樟蠕,之前的我試過幾個(gè)不能用:

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
        <scope>compile</scope>
    </dependency>
第二步:

寫一個(gè)配置類:

@EnableSwagger2
@Configuration
class Swagger2 {
@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()  //RequestHandlerSelectors.any(),所有的路勁都去掃描
            //這個(gè)掃描包的意思一樣靠柑,固定路勁就去相應(yīng)的路勁掃描
            .apis(RequestHandlerSelectors.basePackage("com.example.demo.talkCloud.controller"))
            .paths(PathSelectors.any())
            .build();
}

//就是對(duì)生成的api文檔的一個(gè)描述
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("文檔標(biāo)題")
            .description("文檔描述")
            .termsOfServiceUrl("相關(guān)url")
            .contact("名字-UP主")
            .version("版本:1.0")
            .build();
    }
 }

【注意】:實(shí)現(xiàn)這兩步就能完成文檔的生成了寨辩,可以嘗試用localhost:8080/swagger-ui.html 訪問,端口是spring boot 啟動(dòng)時(shí)設(shè)置的歼冰,自己看靡狞。

第三步:

去你的controller層用注解標(biāo)記Controller,常用的注解我寫在下面了停巷,這些注解都是為了豐富api文檔誕生的耍攘。這里先舉個(gè)例如:

@ApiImplicitParams({
        @ApiImplicitParam(name = "Authorization", value = "Authorization token",
                required = true, dataType = "string", paramType = "header"),
        @ApiImplicitParam(name = "studentId", value = "學(xué)生id", dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "subjectId", value = "科目id", dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "pageSize", value = "頁(yè)大小", dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "pageNo", value = "第幾頁(yè)", dataType = "Integer", paramType = "query"),
})
@ApiOperation(value = "學(xué)生課程表獲取", httpMethod = "GET", response = ResponseEntity.class)
@RequestMapping(value = "student/course/table", method = RequestMethod.GET)
public ResponseEntity saveResourceSec(
        @RequestParam(name = "studentId") Long studentId,
        @RequestParam(name = "subjectId", required = false) Integer subjectId,
        @RequestParam(value = "pageSize", defaultValue = "25") Integer pageSize,
        @RequestParam(value = "pageNo", defaultValue = "1") Integer pageNo,
        @RequestParam(value = "modifiedOn", required = false) Date modifiedOn

) {
    PageWrapper<CourseScheduleObject> result = studentCourseTableService.getStudentCourseById(studentId, subjectId, pageNo, pageSize, modifiedOn);

    return ResponseEntity.ok(result);
}

【常見注解解讀】

其實(shí)自己領(lǐng)悟一下就好榕栏,就按照單詞表名意思畔勤,簡(jiǎn)單!

  • @Api:用在類上扒磁,說明該類的作用
  • @ApiOperation:用在方法上庆揪,說明方法的作用
  • @ApiImplicitParams:用在方法上包含一組參數(shù)說明
  • @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面
    • paramType:
      • header-->請(qǐng)求參數(shù)的獲确镣小:@RequestHeader
      • query-->請(qǐng)求參數(shù)的獲雀组弧:@RequestParam
      • path(用于restful接口)-->請(qǐng)求參數(shù)的獲取@PathVariable
      • cookie:which are passed in the Cookie header, such as Cookie: debug=0; csrftoken=BUSe35dohU3O1MZvDCU
      • body(不常用)
      • form(不常用)
    • name:參數(shù)名
    • value:對(duì)參數(shù)的描述
    • dataType:參數(shù)類型
    • required:參數(shù)是否必須傳
    • defaultValue:參數(shù)的默認(rèn)值
  • @ApiResponses:用于表示一組響應(yīng)
  • @ApiResponse:用在@ApiResponses中,一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
    • code:數(shù)字兰伤,例如400
    • message:信息内颗,例如"請(qǐng)求參數(shù)沒填好"
    • response:拋出異常的類
最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
  • 序言:七十年代末,一起剝皮案震驚了整個(gè)濱河市敦腔,隨后出現(xiàn)的幾起案子均澳,更是在濱河造成了極大的恐慌,老刑警劉巖符衔,帶你破解...
    沈念sama閱讀 222,865評(píng)論 6 518
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件找前,死亡現(xiàn)場(chǎng)離奇詭異,居然都是意外死亡判族,警方通過查閱死者的電腦和手機(jī)躺盛,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 95,296評(píng)論 3 399
  • 文/潘曉璐 我一進(jìn)店門,熙熙樓的掌柜王于貴愁眉苦臉地迎上來形帮,“玉大人槽惫,你說我怎么就攤上這事周叮。” “怎么了界斜?”我有些...
    開封第一講書人閱讀 169,631評(píng)論 0 364
  • 文/不壞的土叔 我叫張陵则吟,是天一觀的道長(zhǎng)。 經(jīng)常有香客問我锄蹂,道長(zhǎng)氓仲,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 60,199評(píng)論 1 300
  • 正文 為了忘掉前任得糜,我火速辦了婚禮敬扛,結(jié)果婚禮上,老公的妹妹穿的比我還像新娘朝抖。我一直安慰自己啥箭,他們只是感情好,可當(dāng)我...
    茶點(diǎn)故事閱讀 69,196評(píng)論 6 398
  • 文/花漫 我一把揭開白布治宣。 她就那樣靜靜地躺著急侥,像睡著了一般。 火紅的嫁衣襯著肌膚如雪侮邀。 梳的紋絲不亂的頭發(fā)上坏怪,一...
    開封第一講書人閱讀 52,793評(píng)論 1 314
  • 那天,我揣著相機(jī)與錄音绊茧,去河邊找鬼铝宵。 笑死,一個(gè)胖子當(dāng)著我的面吹牛华畏,可吹牛的內(nèi)容都是我干的鹏秋。 我是一名探鬼主播,決...
    沈念sama閱讀 41,221評(píng)論 3 423
  • 文/蒼蘭香墨 我猛地睜開眼亡笑,長(zhǎng)吁一口氣:“原來是場(chǎng)噩夢(mèng)啊……” “哼侣夷!你這毒婦竟也來了?” 一聲冷哼從身側(cè)響起仑乌,我...
    開封第一講書人閱讀 40,174評(píng)論 0 277
  • 序言:老撾萬(wàn)榮一對(duì)情侶失蹤百拓,失蹤者是張志新(化名)和其女友劉穎,沒想到半個(gè)月后绝骚,有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體耐版,經(jīng)...
    沈念sama閱讀 46,699評(píng)論 1 320
  • 正文 獨(dú)居荒郊野嶺守林人離奇死亡,尸身上長(zhǎng)有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點(diǎn)故事閱讀 38,770評(píng)論 3 343
  • 正文 我和宋清朗相戀三年压汪,在試婚紗的時(shí)候發(fā)現(xiàn)自己被綠了粪牲。 大學(xué)時(shí)的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片。...
    茶點(diǎn)故事閱讀 40,918評(píng)論 1 353
  • 序言:一個(gè)原本活蹦亂跳的男人離奇死亡止剖,死狀恐怖腺阳,靈堂內(nèi)的尸體忽然破棺而出落君,到底是詐尸還是另有隱情,我是刑警寧澤亭引,帶...
    沈念sama閱讀 36,573評(píng)論 5 351
  • 正文 年R本政府宣布绎速,位于F島的核電站,受9級(jí)特大地震影響焙蚓,放射性物質(zhì)發(fā)生泄漏纹冤。R本人自食惡果不足惜,卻給世界環(huán)境...
    茶點(diǎn)故事閱讀 42,255評(píng)論 3 336
  • 文/蒙蒙 一购公、第九天 我趴在偏房一處隱蔽的房頂上張望萌京。 院中可真熱鬧,春花似錦宏浩、人聲如沸知残。這莊子的主人今日做“春日...
    開封第一講書人閱讀 32,749評(píng)論 0 25
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽(yáng)求妹。三九已至,卻和暖如春佳窑,著一層夾襖步出監(jiān)牢的瞬間制恍,已是汗流浹背。 一陣腳步聲響...
    開封第一講書人閱讀 33,862評(píng)論 1 274
  • 我被黑心中介騙來泰國(guó)打工华嘹, 沒想到剛下飛機(jī)就差點(diǎn)兒被人妖公主榨干…… 1. 我叫王不留吧趣,地道東北人法竞。 一個(gè)月前我還...
    沈念sama閱讀 49,364評(píng)論 3 379
  • 正文 我出身青樓耙厚,卻偏偏與公主長(zhǎng)得像,于是被迫代替她去往敵國(guó)和親岔霸。 傳聞我的和親對(duì)象是個(gè)殘疾皇子薛躬,可洞房花燭夜當(dāng)晚...
    茶點(diǎn)故事閱讀 45,926評(píng)論 2 361

推薦閱讀更多精彩內(nèi)容