Swagger2使用教程

我是kacen汽纤,一個會點前端的java后端開發(fā)工程師。
今天來插曲一下洪添,來介紹一下Swagger的使用绅项。

簡介

??Swagger是為了解決企業(yè)中接口(api)中定義統(tǒng)一標準規(guī)范的文檔生成工具。方便各大后端小基友的懶問題赋续,但是寫注解也是妥妥的麻煩男翰,但是如果版本迭代快或者人員的流動性大,會導致很多問題纽乱。所以很多企業(yè)中都會有統(tǒng)一的規(guī)范文檔蛾绎,來定義接口標準。

注釋和參數(shù)講解

參數(shù)說明:
name -- 參數(shù)名
value --?參數(shù)說明
required -- 是否必須填寫
dataType -- 數(shù)據類型
paramType -- 參數(shù)類型
example -- 舉例
常用注解說明:

  • @Api()用于類鸦列;

表示標識這個類是swagger的資源

  • @ApiOperation()用于方法租冠;

表示一個http請求的操作

  • @ApiParam()用于方法,參數(shù)薯嗤,字段說明顽爹;

表示對參數(shù)的添加元數(shù)據(說明或是否必填等)

  • @ApiModel()用于類

表示對類進行說明,用于參數(shù)用實體類接收

  • @ApiModelProperty()用于方法骆姐,字段

表示對model屬性的說明或者數(shù)據操作更改

  • @ApiIgnore()用于類镜粤,方法捏题,方法參數(shù)

表示這個方法或者類被忽略

  • @ApiImplicitParam() 用于方法

表示單獨的請求參數(shù)

  • @ApiImplicitParams() 用于方法,包含多個 @ApiImplicitParam

具體使用說明:

1.@Api()
  ···
  @Api("測試用例1")
  @Controller
  public class swaggerTestUse(){
  }
2.@ApiOperation()
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
    public void apiOperationSwaggerTest(){
    }
}
3.@ApiParam()
···
@Api("測試用例1")
@Controller
public class swaggerTestUse(){
    @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
    public void apiOperationSwaggerTest(@ApiParam(name = "id", value = "id入參", required = true) Integer id){
    }
}
4.@ApiModel()
···
@ApiModel(description = "測試實體類", value = "測試實體類")
public class Album implements Serializable {
    ···
}

5.@ApiModelProperty()
···
@ApiModel(description = "測試實體類", value = "測試實體類")
public class User implements Serializable {
    @ApiModelProperty(name = "userName", value = "用戶名", required = false, exmaple = "小明")
    private String userName;
}

6.@ApiImplicitParams() 和@ApiImplicitParam()這兩是兄弟就不分開寫了
    ···
  @Api("測試用例1")
  @Controller
  public class swaggerTestUse(){
      @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger測試")
      @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入參", required = true, dataType = "Integer", paramType = "query"),
                        @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
    })
      public void apiOperationSwaggerTest(Integer id, Brand band){
      }
  }

Swagger2實戰(zhàn)/Swagger具體使用說明(附帶環(huán)境參數(shù)開關配置和springboot WebConfiguration的實現(xiàn)過濾)

看完以上基本的使用說明繁仁,接下來我們就開始實戰(zhàn)吧I嫦凇!黄虱!

步驟1:當然是pom文件導入依賴
<!--swagger-->
        <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:啟動類添加@EnableSwagger2注解
@SpringBootApplication
@EnableSwagger2
@ComponentScan(basePackages = {""})//為什么寫這個稚矿,有的小伙伴掃不到包的請手動掃包
public class ServiceGoodsApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceGoodsApplication.class);
    }
}
步驟3:編寫SwaggerConfig文件
@EnableSwagger2
@Configuration
//Profile是方法1(只在dev和test環(huán)境下開啟)
@Profile({"dev","test"})
public class SwaggerConfig implements WebMvcConfigurer {
    //是否開啟swagger,正式環(huán)境一般是需要關閉的捻浦,可根據springboot的多環(huán)境配置進行設置
    //這個是方法2哦晤揣,使用的話在new Docket里添加.Enable方法將參數(shù)放入即可
    @Value(value = "${swagger.show}")
    private Boolean swaggerEnabled;

    /**
    * apiInfo() 增加API相關信息
    * 所有的注解
    * .apis(RequestHandlerSelectors.any()) 
    * 指定部分注解1.Api.class(@APi),2.ApiOperation.class(@ApiOperation),3.ApiImplicitParam.class(@ApiImplicitParam)
    *.apis(RequestHandlerSelectors.withMethodAnnotation(Api.class))
    * 指定包路徑
    * .apis(RequestHandlerSelectors.basePackage("這里填寫需要的路徑"))
    * .paths() 這個是包路徑下的路徑,PathSelectors.any()是包下所有路徑
    */
    @Bean
    public Docket createRestApi() {
        log.info(""+swaggerEnabled);
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                //創(chuàng)建
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成")
                .description("springboot | swagger")
                // 作者信息
                .contact(new Contact("kacen", "https://www.baidu.com", "abc@qq.com"))
                .version("0.0.1")
                .build();
    }

    //這個是可要可不要的,具體看需求
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

}

看到這里有小伙伴在想要指定多包路徑朱灿,但是又不要整個項目那要怎么辦呢昧识,讓我?guī)愀阋徊ǎ?br> 點擊這里看多包配置哦

步驟4:

大功告成啦,請輸入http://服務器ip:端口/swagger-ui.html#/看看你的專屬文檔吧

提示:

?對于是否暴露swagger盗扒,我提供的環(huán)境開關配置只是其中之一哦跪楞,更多的項目采用的是將頁面放到靜態(tài)頁面,再用nginx進行轉發(fā)后侣灶,指定代理環(huán)境訪問哦甸祭。想了解的可以自己試一下哦。

最后編輯于
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
  • 序言:七十年代末褥影,一起剝皮案震驚了整個濱河市池户,隨后出現(xiàn)的幾起案子,更是在濱河造成了極大的恐慌凡怎,老刑警劉巖校焦,帶你破解...
    沈念sama閱讀 206,968評論 6 482
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件,死亡現(xiàn)場離奇詭異统倒,居然都是意外死亡寨典,警方通過查閱死者的電腦和手機,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 88,601評論 2 382
  • 文/潘曉璐 我一進店門房匆,熙熙樓的掌柜王于貴愁眉苦臉地迎上來凝赛,“玉大人,你說我怎么就攤上這事坛缕∧沽裕” “怎么了?”我有些...
    開封第一講書人閱讀 153,220評論 0 344
  • 文/不壞的土叔 我叫張陵赚楚,是天一觀的道長毙沾。 經常有香客問我,道長宠页,這世上最難降的妖魔是什么左胞? 我笑而不...
    開封第一講書人閱讀 55,416評論 1 279
  • 正文 為了忘掉前任寇仓,我火速辦了婚禮,結果婚禮上烤宙,老公的妹妹穿的比我還像新娘遍烦。我一直安慰自己,他們只是感情好躺枕,可當我...
    茶點故事閱讀 64,425評論 5 374
  • 文/花漫 我一把揭開白布服猪。 她就那樣靜靜地躺著,像睡著了一般拐云。 火紅的嫁衣襯著肌膚如雪罢猪。 梳的紋絲不亂的頭發(fā)上,一...
    開封第一講書人閱讀 49,144評論 1 285
  • 那天叉瘩,我揣著相機與錄音膳帕,去河邊找鬼。 笑死薇缅,一個胖子當著我的面吹牛危彩,可吹牛的內容都是我干的。 我是一名探鬼主播泳桦,決...
    沈念sama閱讀 38,432評論 3 401
  • 文/蒼蘭香墨 我猛地睜開眼汤徽,長吁一口氣:“原來是場噩夢啊……” “哼!你這毒婦竟也來了蓬痒?” 一聲冷哼從身側響起泻骤,我...
    開封第一講書人閱讀 37,088評論 0 261
  • 序言:老撾萬榮一對情侶失蹤漆羔,失蹤者是張志新(化名)和其女友劉穎梧奢,沒想到半個月后,有當?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體演痒,經...
    沈念sama閱讀 43,586評論 1 300
  • 正文 獨居荒郊野嶺守林人離奇死亡亲轨,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內容為張勛視角 年9月15日...
    茶點故事閱讀 36,028評論 2 325
  • 正文 我和宋清朗相戀三年,在試婚紗的時候發(fā)現(xiàn)自己被綠了鸟顺。 大學時的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片惦蚊。...
    茶點故事閱讀 38,137評論 1 334
  • 序言:一個原本活蹦亂跳的男人離奇死亡,死狀恐怖讯嫂,靈堂內的尸體忽然破棺而出蹦锋,到底是詐尸還是另有隱情,我是刑警寧澤欧芽,帶...
    沈念sama閱讀 33,783評論 4 324
  • 正文 年R本政府宣布莉掂,位于F島的核電站,受9級特大地震影響千扔,放射性物質發(fā)生泄漏憎妙。R本人自食惡果不足惜库正,卻給世界環(huán)境...
    茶點故事閱讀 39,343評論 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一處隱蔽的房頂上張望厘唾。 院中可真熱鬧褥符,春花似錦、人聲如沸抚垃。這莊子的主人今日做“春日...
    開封第一講書人閱讀 30,333評論 0 19
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽讯柔。三九已至抡蛙,卻和暖如春,著一層夾襖步出監(jiān)牢的瞬間魂迄,已是汗流浹背粗截。 一陣腳步聲響...
    開封第一講書人閱讀 31,559評論 1 262
  • 我被黑心中介騙來泰國打工, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留捣炬,地道東北人熊昌。 一個月前我還...
    沈念sama閱讀 45,595評論 2 355
  • 正文 我出身青樓,卻偏偏與公主長得像湿酸,于是被迫代替她去往敵國和親婿屹。 傳聞我的和親對象是個殘疾皇子,可洞房花燭夜當晚...
    茶點故事閱讀 42,901評論 2 345