Swagger是什么？

Swagger是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful風格的Web服務(wù)?？傮w目標是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。
Swagger的作用主要有以下兩點：

• 接口的文檔在線自動生成。
• 功能測試。

在SpringBoot中使用Swagger2生成接口文檔

1.引入Swagger2相關(guān)依賴。

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.2.2</version>
</dependency>

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

2.在Application.java的同級包路徑下創(chuàng)建Swagger2的配置類Swagger2。

package com.wunian.swagger;

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;

/**
 * @author wunian
 * @desc Swagger配置類
 *
 * @createdate 2019/9/27
 */
@Configuration  //讓spring來加載該類配置
@EnableSwagger2 //啟用Swagger2
public class Swagger2 {

    /**
     * 創(chuàng)建API應(yīng)用
     * createApiInfo() 增加api相關(guān)信息
     * 通過select()函數(shù)返回一個ApiSelectorBuilder實例，用來控制哪些接口暴露給Swagger來展現(xiàn)
     * 采用指定掃描的包路徑來定義指定要建立API的目錄
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(createApiInfo())
                .select()
                //暴露給Swagger的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.wunian.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 創(chuàng)建該API的基本信息
     * 訪問地址：http://localhost:8080/swagger-demo/swagger-ui.html
     * @return
     */
    protected ApiInfo createApiInfo(){
        return new ApiInfoBuilder()
                 //標題
                 .title("使用Swagger2來構(gòu)建SpringBoot Restful APIs")
                 //標題下方的小字
                 .description("詳情請關(guān)注https://swagger.io/resources/open-api/")
                 //組織服務(wù)地址
                 .termsOfServiceUrl("https://swagger.io/resources/open-api/")
                 //開發(fā)者
                 .contact("勿念")
                 //API版本
                 .version("0.1")
                 .build();
    }
}

3.創(chuàng)建HelloController，添加Api方法并使用Swagger注解來對文檔內(nèi)容進行相關(guān)說明。

package com.wunian.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * @author wunian
 * @desc 測試Swagger注解的控制器
 * @createdate 2019/9/27
 */
@Controller
@RequestMapping("/hello")
//用在類上，說明該類的作用
@Api(value = "HelloController|一個用來測試swagger注解的控制器")
public class HelloController {

    @ResponseBody
    @RequestMapping(value = "/getUserName",method= RequestMethod.GET)
    //給方法增加說明，notes是補充的說明
    @ApiOperation(value = "根據(jù)用戶ID獲取用戶姓名",notes = "userId:1為超級管理員，其他為普通用戶")
    //給方法入?yún)⒃黾诱f明，name：參數(shù)名，value：說明參數(shù)的意思，dataType：參數(shù)類型，required：參數(shù)是否必須傳
    //paramType：指定參數(shù)放在哪個地方，
    //header：請求參數(shù)放置于Request Header，使用@RequestHeader獲取
    //query：請求參數(shù)放置于請求地址，使用@RequestParam獲取
    //path：（用于restful接口）-->請求參數(shù)的獲?。篅PathVariable
    //body：（不常用）
    //form（不常用）
    @ApiImplicitParam(paramType = "query",name = "userId",value = "用戶ID",dataType = "int")
    public String getUserName(@RequestParam Integer userId){
        if(userId==1){
            return "Admin";
        }else{
            return "普通用戶";
        }
    }

    @ResponseBody
    //Conntroller中定義的方法必須在@RequestMapper中顯示的指定RequestMethod類型，
    // 否則SawggerUi會默認為全類型皆可訪問， API列表中會生成多條項目。
    @RequestMapping("/updatePassword")
    @ApiOperation(value = "修改用戶密碼",notes = "根據(jù)用戶ID修改密碼")
    //用在方法上包含一組參數(shù)說明
    @ApiImplicitParams({
            //如果paramType與方法參數(shù)獲取使用的注解不一致，會直接影響到參數(shù)的接收。
        @ApiImplicitParam(paramType = "query",name = "userId",value = "用戶ID",required = true,dataType = "int"),
        @ApiImplicitParam(paramType = "query",name = "pwd",value = "舊密碼",required = true,dataType = "String"),
        @ApiImplicitParam(paramType = "query",name = "newPwd",value = "新密碼",required = true,dataType = "String")
    })

    public String updatePassword(@RequestParam(value = "userId")Integer userId,
                                 @RequestParam(value = "pwd")String pwd,
                                 @RequestParam(value = "newPwd")String newPwd){
        if(userId<0){
            return "該用戶不存在";
        }
        if(StringUtils.isEmpty(pwd)||StringUtils.isEmpty(newPwd)){
            return "密碼不能為空";
        }
        if(pwd.equals(newPwd)){
            return "新密碼不能和舊密碼相同";
        }
        return "密碼修改成功";
    }
}

4.在application.properties文件中配置一些基本參數(shù)。

#服務(wù)端口
server.port=8081
#服務(wù)訪問的上下文路徑
server.servlet.context-path=/
#swagger.json的訪問request mapping路徑
springfox.documentation.swagger.v2.path=/api-docs

5.啟動程序，在瀏覽器中訪問http://localhost:8081/swagger-ui.html，出現(xiàn)如下界面說明接口文檔生成成功。

swagger接口文檔

詳細信息

功能測試