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)吧Ｉ嫦凇！黄虱！

步驟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)境訪問哦甸祭。想了解的可以自己試一下哦。

Swagger2使用教程

簡介

注釋和參數(shù)講解

@Api()用于類鸦列；

@ApiOperation()用于方法租冠；

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

@ApiModel()用于類

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

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

@ApiImplicitParam() 用于方法

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