SpringBoot整合Swagger-ui的配置方法

手寫Api文檔的幾個痛點：

1. 文檔需要更新的時候，需要再次發送一份給前端，也就是文檔更新交流不及時。
2. 接口返回結果不明確
3. 不能直接在線測試接口，通常需要使用工具，比如postman
4. 接口文檔太多，不好管理

Swagger也就是為了解決這個問題，當然也不能說Swagger就一定是完美的，當然也有缺點，最明顯的就是代碼移入性比較強。

其他的不多說，想要了解Swagger的，可以去Swagger官網，可以直接使用Swagger editor編寫接口文檔，當然我們這里講解的是SpringBoot整合Swagger2，直接生成接口文檔的方式。

一.引入依賴：

在pom.xml文件中引入swagger2的依賴，版本根據公司要求引入

<!-- 引入swagger2依賴-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
</dependency>

　二.在config配置包中添加Swagger配置類

　代碼展示：

package com.example.config;

import org.springframework.beans.factory.annotation.Value;
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.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * 用@Configuration注解該類，等價於XML中配置beans；
 * 用@Bean標注方法等價於XML中配置bean。
 * Application.class 加上注解@EnableSwagger2 表示開啟Swagger,也可以通過
 * 配置文件設置是否開啟swagger2
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private Boolean enabled;

    /**
     * .apis(RequestHandlerSelectors.basePackage("所需掃描的controller下的所有包")
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger2構建api文檔")
                .description("簡單優雅的restful風格，http://blog.csdn.net/saytime")
                .version("1.0")
                .build();
    }

    private List<ResponseMessage> customerResponseMessage() {
        List<ResponseMessage> list = new ArrayList<>();
        list.add(new ResponseMessageBuilder().code(200).message("請求成功").build());
        list.add(new ResponseMessageBuilder().code(201).message("資源創建成功").build());
        list.add(new ResponseMessageBuilder().code(204).message("服務器成功處理了請求，但不需要返回任何實體內容").build());
        list.add(new ResponseMessageBuilder().code(400).message("請求失敗,具體查看返回業務狀態碼與對應消息").build());
        list.add(new ResponseMessageBuilder().code(401).message("請求失敗,未經過身份認證").build());
        list.add(new ResponseMessageBuilder().code(405).message("請求方法不支持").build());
        list.add(new ResponseMessageBuilder().code(415).message("請求媒體類型不支持").build());
        list.add(new ResponseMessageBuilder().code(500).message("服務器遇到了一個未曾預料的狀況,導致了它無法完成對請求的處理").build());
        list.add(new ResponseMessageBuilder().code(503).message("服務器當前無法處理請求,這個狀況是臨時的，並且將在一段時間以后恢復").build());
        return list;
    }
}

方法一：在啟動類上添加注解@EnableSwagger2注解用來開啟Swagger2

方法二：在配置類application.yml中設置是否開啟Swagger,通過@Value注解引入配置

 @Value("${swagger.enabled}")
    private Boolean enabled;

三.Restful 接口測試

package com.example.demo.controller;

import com.example.demo.service.GradeService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/grade")
public class GradeController {

    @Autowired
    private GradeService gradeService;

    /**
     * 根據姓名查詢成績信息
     * @param name
     * author: zkf
     */
    @ApiOperation(value="獲取成績信息", notes="根據姓名查詢成績信息")
    @ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "String", paramType = "path")
    @GetMapping(value = "/find")
    public String find(@RequestParam String name){

        String score = gradeService.find(name);
        return score;

    }
}　

項目結構：

四.Swagger2文檔

啟動SpringBoot項目，訪問 http://localhost:8081/swagger-ui.html

   

出現這個頁面說明配置成功了，具體里面的內容以及接口測試，應該一看就懂了。這里就不一一截圖了...

五、Swagger注解

swagger通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該注解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams：多個請求參數

 

本文轉自：https://www.cnblogs.com/jtlgb/p/8532433.html