這不做基本介紹了,新手只需要知道是一個接口文檔規范,按照它的規范(注解形式)能自動生成web形式接口文檔,通過url都前后端都可以訪問,方便數據交互就可以了,重點在于使用

spring boot 中swagger2的依賴

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

spring boot已經整合了swagger,就是springfox,其作用就是生成接口文檔,簡化開發.
還有一個依賴是

<dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>0.9.5</version></dependency>

springfox就是由swagger-spingmvc發展而來,前者自然比后者更強大更適用.

在這里只是實用的例子,基本開發夠用,想深入,去官網

springfox官網鏈接

導入依賴后,首先要做的就是寫一個配置類(復制粘貼下方代碼,日常開發基本可以滿足,要求比較高的話可查官網增加配置)

import io.swagger.annotations.ApiOperation; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.HashSet; import java.util.Set;@Configuration @EnableSwagger2 public class SwaggerConfiguration {@Beanpublic Docket createRestApi() {Set<String> producesList = new HashSet<>();producesList.add("application/json");return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).produces(producesList).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}//文檔信息說明和個人信息配置private ApiInfo apiInfo() {return new ApiInfoBuilder().title("我的swagger").description("我的的描述").contact(new Contact("我的郵箱", "", "xxxxxxxx@163.com")).version("1.0").build();} }

寫完配置類后,啟動application就可以訪問swagger web頁面了,
swagger web頁面地址(接口文檔):http://localhost:8080/swagger-ui.html
我們的接口文檔的雛形也就出來了 apiInfo()方法中定義的內容,可對比下圖

接口文檔雛形已經有了,剩下的就是接口實際對接參數了.

@Api(value = "Api value啊", tags = {"Api tags啊"}) @RestController @RequestMapping("/account") public class AccountController {}

上方是一個controller
@Api注解是swagger注解,作用就是對于當前的controller做一個說明

下方是一個controller中的一個方法

@ApiOperation(value = "ApiOperation Value啊", notes = "ApiOperation Note啊")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用戶編號", required = true,dataType = "long"),@ApiImplicitParam(name = "name", value = "用戶名", required = false)})@RequestMapping(value = "/swagger", method = RequestMethod.GET)public String swaggerTest(@RequestParam("id") Long id, @RequestParam("name") String name) {return name + ":" + id;}

@ApiOperation 是非常重要的一個注解,作用于方法上,用來做方法的說明
比如@ApiOperation(values = “獲取用戶信息”) 前端很容易就可以知道,獲取用戶信息要調用這個接口.其中的notes是注意事項,也可以理解成描述,可以將請求參數等信息直接用文字寫到里面,雖然不正式,但是如果能說明白,也可以不需要再用
@ApiImplicitParam @ApiImplicitParams @ApiParam等注解再對參數進行說明,偷懶時候可以這么干.

@ApiImplicitParams相當于 @ApiImplicitParam集合
@ApiImplicitParam是對入參進行說明,但是只是對單個參數說明,比如long id
就用@ApiImplicitParam(name = “id”,value=“用戶編號”, required = true,dataType = “long”) name 必須等于參數名,value是參數說明.還有一個參數是String name 就再用一個注解去說明.但是如果是一個自動封裝的Bean對象,比如Test test 這個注解就不能說明出Test對象中每一個屬性了,也就是@ApiImplicitParam注解只能說明當前對象,但是對向前對象內部結構無法說明,后面會講解.

@ApiParam注解作用基本等同于@ApiImplicitParam

@ApiOperation(value = "swagger啊", notes = "swagger1注意事項")@RequestMapping(value = "/swagger1", method = RequestMethod.GET)public String swaggerTest1(@RequestParam("id") @ApiParam(name="用戶編號",value="用戶號編號說明",required=true)Long id,@RequestParam("name") @ApiParam(name="用戶名字",value="用戶名字說明",required=true) String name) {return name + ":" + id;} 123456

它作用在參數上,也是對參數的說明,@ApiParam中name可以不是參數名,value是對參數的描述,所以選擇用@ApiParam還是@ApiImplicitParam 可以自己決定,不過我比較推薦,基本數據類型用@ApiImplicitParam, Bean類型用@ApiParam.

最后一個方法

@ApiOperation(value = "swagger2啊", notes = "swagger2注意事項")@RequestMapping(value = "/swagger2", method = RequestMethod.POST)public String swaggerTest2(@RequestBody @ApiParam(name="用戶對象",value="用戶對象說明",required=true) Test test) {return test.getString2() + ":" + test.getString1();}

這樣子只能對于test這個對象進行說明,但是內部屬性,沒有辦法說明,因為我們是json自動轉對象,所以有必要說明下test中每個字段,前端也好傳參,要說明自定義對象,需要用@ApiModel 和@ApiModelProperty 注解

@ApiModel(value="test對象",description="test測試") public class Test {@ApiModelProperty(name = "string1",value = "第一個string",dataType = "String",example = "string1example",required = true)private String string1;@ApiModelProperty(name = "string2",value = "第二個string",dataType = "String",example = "string2example",required = false)private String string2;///getter setter toString}

@ApiModel注解作用于類上,是對類的說明,@ApiModelProperty是對屬性的說明

以上就是springfox(swagger)的基本使用,開發中用的最多的幾個注解已經說明了,至于其他的注解我現在基本不用,所以不再說明.要學習springfox,就多寫幾個接口,用幾次注解,熟悉一下web 頁面,很快就可以學會~

總結

以上是生活随笔為你收集整理的Swagger2的使用的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。