SpringBoot中使用Swagger生成RESTful規範API文檔

Swagger是爲了描述一套標準的而且是和語言無關的REST API的規範。對於外部調用者來說，只需通過Swagger文檔即可清楚Server端提供的服務，而不需去閱讀源碼或接口文檔說明。

官方網站爲：http://swagger.io
中文網站：http://www.sosoapi.com

背景
前後端分離
1、前後端僅僅通過異步接口(AJAX/JSON)來編程
2、前後端都各自有自己的開發流程，構建工具，測試集合
3、關注點分離，前後端變得相對獨立並鬆耦合

開發流程
1、後臺編寫和維護接口文檔，在 API 變化時更新接口文檔
2、後臺根據接口文檔進行接口開發
3、前端根據接口文檔進行開發
4、開發完成後聯調和提交測試

三大功能
1、Swagger Editor: Swagger提供的一個編輯器，用來通過Swagger提供的特定的YAML語法來編寫API文檔
2、Swagger Codegen: 代碼生成器
3、Swagger UI: YAML語法定義我們的RESTful API，然後它會自動生成一篇排版優美的API文檔，並且提供實時預覽。

面臨問題
1、沒有統一的文檔編寫規範，導致文檔越來越亂，無法維護和閱讀。
2、開發中的接口增刪改等變動，需要較大的溝通成本。
3、對於一個新需求，前端開發的接口調用和自測依賴後臺開發完畢。
4、將接口的風險後置，耽誤項目時間。

解決方法
1、接口文檔服務器 -- 解決接口文檔編輯和維護的問題。
2、mock 數據 -- 解決前端開發依賴真實後臺接口的問題。

一、接口文檔服務器：
1、修改pom.xml，添加maven依賴

<!-- Swagger -->
        <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>

2、添加Swagger配置類，Swagger會默認把所有Controller中的RequestMapping方法都生成API出來，實際上我們一般只需要標準接口的（像返回頁面的那種Controller方法我們並不需要），所有你可以按下面的方法來設定要生成API的方法的要求。
如下我針對RestController註解的類和ResponseBody註解的方法才生成Swaager的API，並且排除了特定的類，代碼如下：

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;
import springfox.documentation.service.Tag;


@Configuration
@EnableSwagger2
public class Swagger2Config {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bocom.gzxf.jcsj.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("實戰指揮平臺--基礎數據API說明文檔")
                .description("2017.11.9上線版本")
                //.termsOfServiceUrl("http://mindao.com.cn")
                .contact("智慧消防研發部")
                .version("1.0")
                .build();
    }
}

3、對外接口類配置

/**
 * Controller
 *
 * @since 2017年9月8日上午9:39:32
 * @author shanming.yang
 *
 */
@RestController
@RequestMapping("/user")
@Validated
@Api(value = "USER", description = "測試UserController")
public class UserController {
	private static Logger logger = LogManager.getLogger(UserController.class.getName());
	@Resource
	private DemoService demoService;


	@RequestMapping(value="",method={RequestMethod.GET })
    	@ApiOperation(value = "查詢個人信息接口",notes = "查詢個人信息接口")
    	@ApiImplicitParams({
        	@ApiImplicitParam(paramType = "header", dataType="string", name = "token", value = "訪問憑證", required = true),
    	}) 
	public List<Demo> query(@RequestParam("page") int page,
			@RequestParam("count") int count) {
		return demoService.query(page, count);
	}
	
	@RequestMapping(value="",method={RequestMethod.POST })
	@ApiOperation(value = "增加個人信息接口",notes = "增加個人信息接口")
	public void insert(@RequestAttribute("name") String name) {
		Demo model = new Demo();
		String uuid = UUID.randomUUID().toString().replaceAll("-", "");
		model.setId(uuid);
		model.setAge("25");
		model.setName(name);
		demoService.insert(model);
	}
}

經過這3步配置後，我們啓動服務後，訪問：http://localhost:8080/swagger-ui.html 就完成了集成。

Swagger2默認將所有的Controller中的RequestMapping方法都會暴露，然而在實際開發中，我們並不一定需要把所有API都提現在文檔中查看，這種情況下，使用註解@ApiIgnore來解決，如果應用在Controller範圍上，則當前Controller中的所有方法都會被忽略，如果應用在方法上，則對應用的方法忽略暴露API。

4、相關注解解讀

1. @Api
用在類上，說明該類的作用
@Api(value = "UserController", description = "用戶相關api")

2. @ApiOperation
用在方法上，說明方法的作用
@ApiOperation(value = "查找用戶", notes = "查找用戶", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

3 @ApiImplicitParams
用在方法上包含一組參數說明

4. @ApiImplicitParam
用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
paramType：參數放在哪個地方
header–>請求參數的獲取：@RequestHeader
query–>請求參數的獲取：@RequestParam
path（用於restful接口）–>請求參數的獲取：@PathVariable
body（不常用）
form（不常用）
name：參數名
dataType：參數類型
required：參數是否必須傳
value：參數的意思
defaultValue：參數的默認值
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
5. @ApiResponses
用於表示一組響應

6. @ApiResponse
用在@ApiResponses中，一般用於表達一個錯誤的響應信息
code：數字，例如400
message：信息，例如”請求參數沒填好”
response：拋出異常的類
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
7. @ApiModel
描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModel(value = "用戶實體類")

8. @ApiModelProperty
描述一個model的屬性
@ApiModelProperty(value = "登錄用戶")

Swagger接口請求有幾個：
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-resources/configuration/security

附：使用Swagger生成JAVA Mock Server（Springboot）代碼
http://blog.csdn.net/a78270528/article/details/78530702