快捷導(dǎo)航

spring boot整合Swagger2的示例代碼

更新時(shí)間：2017年04月27日 16:07:39 作者：牛頭人

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的 Web 服務(wù)。這篇文章主要介紹了spring boot整合Swagger2,需要的朋友可以參考下

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的 Web 服務(wù)。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來(lái)更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來(lái)始終保持同步。Swagger 讓部署管理和使用功能強(qiáng)大的API從未如此簡(jiǎn)單。

1.代碼示例

1).在pom.xml文件中引入Swagger2

 <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>

2).在Application同級(jí)目錄下添加Swagger2的配置類

package com.example;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Config {
 @Bean
 public Docket createRestApi() {
  return new Docket(DocumentationType.SWAGGER_2)
    .apiInfo(apiInfo())
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.example"))
    .paths(PathSelectors.any())
    .build();
 }
 private ApiInfo apiInfo() {
  return new ApiInfoBuilder()
    .title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")
    .description("spring boot整合swagger2")
    .termsOfServiceUrl("www.baidu.com")
    .contact("牛頭人")
    .version("1.0")
    .build();
 }
}

如上代碼所示，通過(guò) @Configuration 注解，讓Spring來(lái)加載該類配置。再通過(guò) @EnableSwagger2 注解來(lái)啟用Swagger2。

通過(guò) createRestApi 函數(shù)創(chuàng)建 Docket 的Bean之后， apiInfo() 用來(lái)創(chuàng)建該Api的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中）。 select() 函數(shù)返回一個(gè) ApiSelectorBuilder 實(shí)例用來(lái)控制哪些接口給Swagger來(lái)展現(xiàn)，本例采用指定掃描的包路徑來(lái)定義，Swagger會(huì)掃描該包下所有Controller定義的API，并產(chǎn)生文檔內(nèi)容（除了被 @ApiIgnore 指定的請(qǐng)求）。

3).新建User實(shí)體類

package com.example.swagger2;
public class User {
 private String id;
 private String name;
 public String getId() {
  return id;
 }
 public void setId(String id) {
  this.id = id;
 }
 public String getName() {
  return name;
 }
 public void setName(String name) {
  this.name = name;
 }
}

4).新建SwaggerDemoController類

package com.example.swagger2;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@RestController
@RequestMapping(value="/api") 
@Api("SwaggerDemoController相關(guān)api")
public class SwaggerDemoController {
 static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());
 @ApiOperation(value="獲取用戶列表", notes="")
 @ApiResponses({
  @ApiResponse(code=400,message="請(qǐng)求參數(shù)沒(méi)填好"),
  @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
 })
 @RequestMapping(value={""}, method=RequestMethod.GET)
 public List<User> getUserList() {
  List<User> r = new ArrayList<User>(users.values());
  return r;
 }
 @ApiOperation(value="創(chuàng)建用戶", notes="根據(jù)User對(duì)象創(chuàng)建用戶")
 @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體user", required = true, dataType = "User")
 @ApiResponses({
  @ApiResponse(code=400,message="請(qǐng)求參數(shù)沒(méi)填好"),
  @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
 })
 @RequestMapping(value="", method=RequestMethod.POST)
 public String postUser(@RequestBody User user) {
  users.put(user.getId(), user);
  return "success";
 }
 @ApiOperation(value="獲取用戶詳細(xì)信息", notes="根據(jù)url的id來(lái)獲取用戶詳細(xì)信息")
 @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String")
 @ApiResponses({
  @ApiResponse(code=400,message="請(qǐng)求參數(shù)沒(méi)填好"),
  @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
 })
 @RequestMapping(value="/{id}", method=RequestMethod.GET)
 public User getUser(@PathVariable String id) {
  System.out.println("id="+id);
  return users.get(id);
 }
 @ApiOperation(value="更新用戶詳細(xì)信息", notes="根據(jù)url的id來(lái)指定更新對(duì)象，并根據(jù)傳過(guò)來(lái)的user信息來(lái)更新用戶詳細(xì)信息")
 @ApiImplicitParams({
   @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String"),
   @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體user", required = true, dataType = "User")
 })
 @ApiResponses({
  @ApiResponse(code=400,message="請(qǐng)求參數(shù)沒(méi)填好"),
  @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
 })
 @RequestMapping(value="/{id}", method=RequestMethod.PUT)
 public String putUser(@PathVariable String id, @RequestBody User user) {
  System.out.println("id="+id);
  User u = users.get(id);
  u.setName(user.getName());
  users.put(id, u);
  return "success";
 }
 @ApiOperation(value="刪除用戶", notes="根據(jù)url的id來(lái)指定刪除對(duì)象")
 @ApiImplicitParam(name = "id", value = "用戶ID",paramType="path", required = true, dataType = "String")
 @ApiResponses({
  @ApiResponse(code=400,message="請(qǐng)求參數(shù)沒(méi)填好"),
  @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
 })
 @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
 public String deleteUser(@PathVariable String id) {
  System.out.println("id="+id);
  users.remove(id);
  return "success";
 }
}

說(shuō)明：

    @Api：用在類上，說(shuō)明該類的作用
    @ApiOperation：用在方法上，說(shuō)明方法的作用
    @ApiImplicitParams：用在方法上包含一組參數(shù)說(shuō)明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面
        paramType：參數(shù)放在哪個(gè)地方
            header-->請(qǐng)求參數(shù)的獲?。篅RequestHeader
            query-->請(qǐng)求參數(shù)的獲?。篅RequestParam
            path（用于restful接口）-->請(qǐng)求參數(shù)的獲?。篅PathVariable
            body（不常用）
            form（不常用）
        name：參數(shù)名
        dataType：參數(shù)類型
        required：參數(shù)是否必須傳
        value：參數(shù)的意思
        defaultValue：參數(shù)的默認(rèn)值
    @ApiResponses：用于表示一組響應(yīng)
    @ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
        code：數(shù)字，例如400
        message：信息，例如"請(qǐng)求參數(shù)沒(méi)填好"
        response：拋出異常的類
    @ApiModel：描述一個(gè)Model的信息（這種一般用在post創(chuàng)建的時(shí)候，使用@RequestBody這樣的場(chǎng)景，請(qǐng)求參數(shù)無(wú)法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）
        @ApiModelProperty：描述一個(gè)model的屬性