文章轉(zhuǎn)載自： https://blog.52itstyle.com/archives/1473/

一、簡介

Swagger 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。總體目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新 。接口的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。Swagger 讓部署管理和使用功能強大的API從未如此簡單。
在實際開發(fā)過程中，我們的RESTful API就有可能要面對多個開發(fā)人員或多個開發(fā)團隊：IOS開發(fā)、Android開發(fā)、Web開發(fā)等。為了減少與其他團隊平時開發(fā)期間的頻繁溝通成本，傳統(tǒng)做法我們會創(chuàng)建一份RESTful API文檔來記錄所有接口細節(jié)，然而這樣的做法有以下幾個問題：
由于接口眾多，并且細節(jié)復(fù)雜（需要考慮不同的HTTP請求類型、HTTP頭部信息、HTTP請求內(nèi)容等），高質(zhì)量地創(chuàng)建這份文檔本身就是件非常吃力的事，下游的抱怨聲不絕于耳
隨著時間推移，不斷修改接口實現(xiàn)的時候都必須同步修改接口文檔，而文檔與代碼又處于兩個不同的媒介，除非有嚴格的管理機制，不然很容易導(dǎo)致不一致現(xiàn)象
而swagger完美的解決了上面的幾個問題，并與Spring boot程序配合組織出強大RESTful API文檔。它既可以減少我們創(chuàng)建文檔的工作量，同時說明內(nèi)容又整合入實現(xiàn)代碼中，讓維護文檔和修改代碼整合為一體，可以讓我們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能 來調(diào)試每個RESTful API。

二、添加Swagger2依賴

<!-- swagger2 文檔 截止目前 為最新版本 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

三、創(chuàng)建Swagger2配置類

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

@Configuration //讓Spring來加載該類配置
@EnableSwagger2 //啟用Swagger2
public class Swagger2 {
    @Bean
    public Docket alipayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("支付寶API接口文檔")  
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.alipay"))
                .paths(PathSelectors.any()).build();
    }
    @Bean
    public Docket weixinpayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("微信API接口文檔")  
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.weixinpay"))
                .paths(PathSelectors.any()).build();
    }
    @Bean
    public Docket unionpayApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("銀聯(lián)API接口文檔")  
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.unionpay"))
                .paths(PathSelectors.any()).build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("支付系統(tǒng)")
                .description("微信、支付寶、銀聯(lián)支付服務(wù)")
                .termsOfServiceUrl("http://blog.52itstyle.com")
                .contact(new Contact("科幫網(wǎng) ", "http://blog.52itstyle.com", "345849402@qq.com"))
                .version("1.0").build();
    }
}

四、添加API注解

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

代碼實現(xiàn)：
    
    @Api(tags ="銀聯(lián)支付")
    @Controller
    @RequestMapping(value = "unionpay")
    public class UnionPayController {
        private static final Logger logger =    LoggerFactory.getLogger(AliPayController.class);
        @Autowired
        private IUnionPayService unionPayService;
    @ApiOperation(value="銀聯(lián)支付主頁")   @RequestMapping(value="index",method=RequestMethod.GET)
        public String   index() {
            return "unionpay/index";
        }
    @ApiOperation(value="電腦支付")    
    @RequestMapping(value="pcPay",method=RequestMethod.POST)
    @ApiImplicitParam(name = "product", value = "產(chǎn)品信息", required = true, dataType = "Product")
       public String  pcPay(Product product,ModelMap map) {
            logger.info("電腦支付");
            product.setPayWay(PayWay.PC.getCode());
            String form  =  unionPayService.unionPay(product);
            map.addAttribute("form", form);
            return "unionpay/pay";
        }
    @ApiIgnore//使用該注解忽略這個API
    @ApiOperation(value="手機H5支付")
    @RequestMapping(value="mobilePay",method=RequestMethod.POST)
        public String  mobilePay(Product product,ModelMap map) {
            logger.info("手機H5支付");
            product.setPayWay(PayWay.MOBILE.getCode());
            String form  =  unionPayService.unionPay(product);
            map.addAttribute("form", form);
            return "unionpay/pay";
        }
    }

訪問

配置完成后，我們重啟服務(wù)，訪問地址 http://localhost:8080/項目名/swagger-ui.html，如：

http://localhost:8080/springboot_pay/swagger-ui.html

1.png