swagger2可以減少我們的編寫文檔工作露懒，尤其現(xiàn)在是前后端分離。后端寫好接口之后還需要寫API使用文檔給客戶端人員砂心，尤其是在接口變更之后懈词，文檔往往就得不到及時(shí)的更新甚至是遺忘，導(dǎo)致文檔最終變得不可信辩诞。這個(gè)框架可以幫助解決此類問題坎弯，減少后端人員的工作量，同時(shí)還能保持維護(hù)文檔的地方只有一處。

這個(gè)框架也只是幫助減少上述問題抠忘，如果只是修改了代碼撩炊，而沒有更新相應(yīng)的描述信息等，也是會(huì)存在上述問題的崎脉。

一拧咳、準(zhǔn)備工作

添加依賴，在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>

二囚灼、配置swagger2

在Application.java平級(jí)的包下骆膝，新建一個(gè)Swagger2的類，內(nèi)容如下灶体，其中需要注意的是createRestApi方法下的包名為自己項(xiàng)目中的包名阅签，一般為控制器所在的包。

**
 * Swagger2配置類
 * 1）在集成spring boot時(shí)蝎抽，放在與Application.java同級(jí)目錄下
 * 2）@Configuration注解的作用是讓spring 來加載該類的配置
 * 3）@EnableSwagger2 是用來啟用swagger2
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:14
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    /**
     * 指定掃描包的路徑來指定要?jiǎng)?chuàng)建API的目錄政钟，一般是控制器這個(gè)包
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xiaozhao.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 設(shè)置API的基本信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的公司")
                .description("后端接口說明文檔")
                .termsOfServiceUrl("http://www.reibang.com")
                .version("1.0")
                .build();
    }
}

image.png

三、swagger2常用注解說明

• @Api()
  value： 不能顯示到UI上
  tags：一個(gè)字符串?dāng)?shù)組织中，說明整個(gè)類的作用锥涕，會(huì)顯示在UI上。此處發(fā)現(xiàn)一個(gè)問題狭吼，就是為中文時(shí)层坠，導(dǎo)致接口在UI上不能展開。

修飾在類上刁笙，描述一個(gè)類的作用破花。例如：

@Api(value = "歡迎", tags = {"用戶操作接口說明"})
public class HelloController {
}

• @ApiOperation()
  value：說明方法的用途、作用
  notes：方法的備注說明
  修飾方法疲吸，說明方法的作用座每，例如：

    @GetMapping("/hi")
    @ApiOperation(value = "問候語(yǔ)", notes = "這是一個(gè)問候", httpMethod = "GET")
    public String hello() {
        return "Hell World";
    }

• @ApiImplicitParams
  是一個(gè)@ApiImplicitParam的數(shù)組，用在請(qǐng)求的方法上摘悴，包含一組參數(shù)說明

• @ApiImplicitParam
  name：參數(shù)名
  value：參數(shù)的漢字說明峭梳，描述信息
  required：是否必需
  dataType：參數(shù)類型，默認(rèn)String蹂喻，其它值dataType="Integer" 或dataType="User" 或 ......
  defaultValue：參數(shù)的默認(rèn)值
  paramType：參數(shù)放在哪個(gè)地方

            header --> 請(qǐng)求參數(shù)的獲却型帧：@RequestHeader
            query --> 請(qǐng)求參數(shù)的獲取：@RequestParam
            path（用于restful接口）--> 請(qǐng)求參數(shù)的獲瓤谒摹：@PathVariable
            body（不常用）
            form（不常用）  

用來說明方法的參數(shù)孵运，例如：

    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
    @ApiOperation(value = "更新信息", notes = "根據(jù)url的id來指定更新用戶信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用戶實(shí)體", required = true, dataType = "User")
    })
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        System.out.println(id);
        System.out.println(user.getId());
        System.out.println(user.getName());
        return "修改成功";
    }

• @ApiParam
  name：參數(shù)名
  value：參數(shù)的漢字說明，描述信息
  required：是否必需
  用于方法蔓彩、參數(shù)的說明治笨，例如：

    @ApiOperation("更改用戶信息")
    @PostMapping("/updateUserInfo")
    public int test(@RequestBody @ApiParam(name = "用戶對(duì)象", value = "傳入json格式", required = true) User user) {
        return 1;
    }

• @ApiResponses
  是一個(gè)@ApiResponse的數(shù)組驳概，用于請(qǐng)求的方法上，表示一組響應(yīng)

• @ApiResponse()
  code：標(biāo)準(zhǔn)的http響應(yīng)碼旷赖，例如404顺又，500，502等
  message：錯(cuò)誤信息杠愧，例如“參數(shù)錯(cuò)誤”
  response：拋出異常的類
  修飾方法待榔，表達(dá)一個(gè)錯(cuò)誤的響應(yīng)，例如：

    @GetMapping("/hi")
    @ApiOperation(value = "問候語(yǔ)", notes = "這是一個(gè)問候", httpMethod = "GET")
    @ApiResponses({
            @ApiResponse(code = 400, message = "請(qǐng)求參數(shù)沒填好"),
            @ApiResponse(code = 404, message = "請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
    public String hello() {
        return "Hell World";
    }

• @ApiModel()
  value：類名
  description：描述

一般用于參數(shù)為一個(gè)實(shí)體類時(shí)流济，說明這個(gè)類的各項(xiàng)屬性的含義锐锣。只能修飾在類上，需要配合@ApiProperty一起使用绳瘟，例如：

@ApiModel
public class User implements Serializable {
    private static final long serialVersionUID = -1084928517040754103L;
}

• @ApiModelProperty()
  name：屬性名稱
  value：描述
  dataType：屬性的數(shù)據(jù)類型
  required：是否必填
  example：舉例說明
  hidden：在文檔上是否不可見

修飾實(shí)體類的屬性雕憔，例如：

    @ApiModelProperty(value = "用戶id", name = "id", required = false)
    private Integer id;

    @ApiModelProperty(value = "用戶名稱", name = "name", required = true,example = "張颯")
    private String name;


   //省略  getter and setter 

image.png

*@ApiIgnore
可以修飾類或者非法，然后在文檔中不再顯示

四糖声、項(xiàng)目中使用

用戶實(shí)體類

/**
 * 用戶實(shí)體類
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:35
 */
@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = -1084928517040754103L;
    @ApiModelProperty(value = "用戶id", name = "id", required = false)
    private Integer id;

    @ApiModelProperty(value = "用戶名稱", name = "name", required = true, example = "張颯")
    private String name;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                '}';
    }
}

控制器

/**
 * swagger2 示例
 *
 * @author xiaozhao
 * @date 2018/10/19下午3:17
 */
@RestController
@RequestMapping("/api")
@Api(value = "Welcome", tags = {"User Guide"})
public class HelloController {

    /**
     * 無參數(shù)斤彼，只有說明
     *
     * @return 返回字符串
     */
    @GetMapping("/hi")
    @ApiOperation(value = "問候語(yǔ)", notes = "這是一個(gè)問候", httpMethod = "GET")
    @ApiResponses({
            @ApiResponse(code = 400, message = "請(qǐng)求參數(shù)沒填好"),
            @ApiResponse(code = 404, message = "請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
    public String hello() {
        return "Hell World";
    }

    /**
     * 無參數(shù)
     *
     * @return 返回一個(gè)對(duì)象
     */
    @GetMapping("/list")
    @ApiOperation(value = "列表", notes = "獲取用戶列表", httpMethod = "GET")
    public HttpResult list() {
        HttpResult httpResult = new HttpResult();
        httpResult.setCode(0);
        httpResult.setMsg("");
        List<User> list = new ArrayList<>();
        User user = new User();
        user.setId(1);
        user.setName("James");
        list.add(user);
        httpResult.setData(list);
        return httpResult;
    }


    /**
     * 有一個(gè)簡(jiǎn)單類型的參數(shù)，rest風(fēng)格
     *
     * @param id
     * @return
     */
    @RequestMapping(value = "/find/{id}", method = RequestMethod.GET)
    @ApiOperation(value = "查找用戶", notes = "查找某個(gè)用戶的詳細(xì)信息")
    @ApiImplicitParam(name = "id", value = "用戶唯一標(biāo)識(shí)", required = true, dataType = "Long", paramType = "path")
    public User getBook(@PathVariable Long id) {
        System.out.println(id);
        User user = new User();
        user.setId(1);
        user.setName("庫(kù)里");
        return user;
    }

    /**
     * 有一個(gè)引用類型的參數(shù)
     *
     * @param user
     * @return
     */
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ApiOperation(value = "添加用戶", notes = "添加一個(gè)新的用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體", required = true, dataType = "User")
    public String postBook(@RequestBody User user) {
        System.out.println(user);
        return "添加用戶成功";
    }


    /**
     * 有一個(gè)簡(jiǎn)單類型的參數(shù)和一個(gè)引用類型的參數(shù)
     *
     * @param id
     * @param user
     * @return
     */
    @RequestMapping(value = "/update/{id}", method = RequestMethod.PUT)
    @ApiOperation(value = "更新信息", notes = "根據(jù)url的id來指定更新用戶信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用戶實(shí)體", required = true, dataType = "User")
    })
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        System.out.println(id);
        System.out.println(user.getId());
        System.out.println(user.getName());
        return "修改成功";
    }

    /**
     * 有一個(gè)Long的參數(shù)
     *
     * @param id
     * @return
     */
    @RequestMapping(value = "/del_user/{id}", method = RequestMethod.DELETE)
    @ApiOperation(value = "刪除用戶", notes = "根據(jù)id來刪除指定用戶")
    @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long", paramType = "path")
    public String deleteUser(@PathVariable Long id) {
        System.out.println("刪除用戶：" + id);
        return "success";
    }

    /**
     * 使用該注解忽略這個(gè)API
     *
     * @return
     */
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    @ApiIgnore
    public String jsonTest() {
        return " hi you!";
    }


    @ApiOperation("更改用戶信息")
    @PostMapping("/updateUserInfo")
    public int test(@RequestBody @ApiParam(name = "用戶對(duì)象", value = "傳入json格式", required = true) User user) {
        return 1;
    }
}

最后運(yùn)行項(xiàng)目蘸泻，然后在瀏覽器中打開 http://localhost:8080/swagger-ui.html

看到如下界面

image.png

image.png

完整代碼

https://github.com/xiaozhaowen/spring-boot-in-action/tree/master/springboot-swagger2