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

1、Swagger簡(jiǎn)介

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。

官網(wǎng)： ( https://swagger.io/ )

主要作用是：

1. 使得前后端分離開(kāi)發(fā)更加方便，有利于團(tuán)隊(duì)協(xié)作

2. 接口的文檔在線自動(dòng)生成，降低后端開(kāi)發(fā)人員編寫(xiě)接口文檔的負(fù)擔(dān)

3. 功能測(cè)試

Spring已經(jīng)將Swagger納入自身的標(biāo)準(zhǔn)，建立了Spring-swagger項(xiàng)目，現(xiàn)在叫 Springfox。通過(guò)在項(xiàng)目中引入Springfox ，即可非常簡(jiǎn)單快捷的使用Swagger。

2、整合步驟

項(xiàng)目整體架構(gòu)如下：

首先構(gòu)建一個(gè)maven項(xiàng)目，添加依賴(lài)，我本項(xiàng)目只是一個(gè)子模塊，所以相應(yīng)的版本都是依賴(lài)于父版本的，看不到版本號(hào)，swagger使用的是2.9.2版本

<dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
        </dependency>
</dependencies>

創(chuàng)建Swagger配置類(lèi)SwaggerConfig

package com.swagger.config;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;
@Configuration
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
public class SwaggerConfig implements WebMvcConfigurer {
    @Bean
    public Docket buildDocket() {
        // 要掃描的API(Controller)基礎(chǔ)包
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo buildApiInfo() {
        Contact contact = new Contact("開(kāi)發(fā)者", "", "");
        return new ApiInfoBuilder()
                .title("測(cè)試‐應(yīng)用API文檔")
                .description("")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
    /*** 添加靜態(tài)資源文件，外部可以直接訪問(wèn)地址 ** @param registry */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry
                .addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        registry
                .addResourceHandler("swagger‐ui.html")
                .addResourceLocations("classpath:/META‐INF/resources/");
        registry
                .addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META‐INF/resources/webjars/");
    }
}

在Controller層創(chuàng)建SwaggerController類(lèi)方便測(cè)試，并添加swagger相應(yīng)注解

package com.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(value = "測(cè)試平臺(tái) ",tags = "測(cè)試平臺(tái)")
@RestController
public class SwaggerController {
    @ApiOperation("測(cè)試")
    @GetMapping(path = "/hello")
    public String hello(){
        return "hello";
    }
    @ApiOperation("測(cè)試2")
    @ApiImplicitParam(name = "name",value = "姓名",required = true,dataType = "string")
    @GetMapping("/hi")
    public String hi(String name){
        return "hi : "+name;
    }
}

常用Swagger注解如下：

@Api：修飾整個(gè)類(lèi)，描述Controller的作用 @ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口
@ApiParam：?jiǎn)蝹€(gè)參數(shù)的描述信息
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiModelProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
@ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)的描述信息

創(chuàng)建啟動(dòng)類(lèi)SwaggerApplication

package com.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2     //開(kāi)啟swagger
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

啟動(dòng)SwaggerApplication ，訪問(wèn)http://localhost:8080/swagger-ui.html