java效率開發之使用swagger, 同時推薦使用加強swagger-UI

前言

現代化的研發組織架構中，一個研發團隊基本包括了 產品組、後端組、前端組、APP端研發、 測試組、 UI組等，各個細分組織人員各司其職，共同完成產品的全週期工做。如何進行組織架構內的有效高效溝通就顯得尤爲重要。其中，如何構建一份合理高效的接口文檔更顯重要。

接口文檔橫貫各個端的研發人員，可是因爲接口衆多，細節不一，有時候理解起來並非那麼容易，引發‘內戰’也在所不免， 而且維護也是一大難題。

17 年項目使用markdown 文檔, 項目大了, 18年轉而引用RAP文檔;

相似RAP文檔管理系統，將接口文檔進行在線維護，方便了前端和APP端人員查看進行對接開發 ，可是仍是存在如下幾點問題：

• 文檔是接口提供方手動導入的，靜態文檔,項目大查閱麻煩；
• 多人開發時,容易形成文檔鎖定,沒法繼續編寫;
• 維護的難度不小。
• 後端開發人員編寫重複,工做量大
• 確實接口測試,通常都是本身下載postman調試接口

Swagger的出現能夠完美解決以上傳統接口管理方式存在的痛點。

解放後端開發人員,全程自動生成,無需頻繁切換,工具,一切都在java中;

本文介紹SpringBoot整合Swagger2的流程。

什麼是Swagger

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。

做用

1. 接口文檔在線生成
2. 功能測試

實用語法

@Api：用在類上，說明該類的做用。

@ApiOperation：註解來給API增長方法說明。

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

@ApiImplicitParam：用來註解來給方法入參增長說明。

@ApiResponses：用於表示一組響應

@ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息

    l   code：數字，例如400

    l   message：信息，例如"請求參數沒填好"

    l   response：拋出異常的類  

@ApiModel：描述一個Model的信息（通常用在請求參數沒法使用@ApiImplicitParam註解進行描述的時候）

    l   @ApiModelProperty：描述一個model的屬性

 

paramType：指定參數放在哪一個地方	header：請求參數放置於Request Header，使用@RequestHeader獲取 query：請求參數放置於請求地址，使用@RequestParam獲取 path：（用於restful接口）-->請求參數的獲取：@PathVariable body：（不經常使用） form（不經常使用）
name：參數名
dataType：參數類型
required：參數是否必須傳	true | false
value：說明參數的意思
defaultValue：參數的默認值

 

簡單介紹完畢,開始正式組合搭建了

springboot + swagger 搭建

1. dependency引用

<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>
<!-- swagger2 加強UI ,擁有好看的界面, 和接口分組,排序等功能,如不引用可自行刪除-->
<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.8.7</version>
            </dependency>

 

2. config配置

package com.xxx.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
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;

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI  //第三方swagger加強API註解
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        /**
         * @Author wuxw
         * @Description //關於分組接口,可後期根據多模塊,拆解爲根據模塊來管理API文檔
         * @Date 10:18 2019/3/15
         * @Param []
         * @return springfox.documentation.spring.web.plugins.Docket
         **/
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("後臺管理接口")
                .apiInfo(apiInfo())
                .host("localhost:8082")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX項目API")
                .description("系統化信息化XX平臺,爲您提供最優質的服務")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

3. 方法註釋

劃重點: 註解Controller接口方法時,務必指定@GetMappering,@PostMapping等, 不然swagger 會生成多個相同api的接口;

4.   訪問入口

如未使用加強ui, 則訪問路徑爲:  http://localhost:8080/swagger-ui.html  (默認)

加強UI 訪問路徑: http://localhost:8080/doc.html

其中, 若是使用加強ui, doc.html404 找不到的話, 可修改application類,重載指定方法實現;

package com.xx.xx;

import lombok.extern.slf4j.Slf4j;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Slf4j
@SpringBootApplication
@MapperScan("com.xx.xx.*.mapper")
public class SystemApplication  implements WebMvcConfigurer {

	public static void main(String[] args) {
		long beginTime = System.currentTimeMillis();
		SpringApplication.run(SystemApplication.class, args);
		long endTime = System.currentTimeMillis();
        log.error("-----------啓動完畢---------;啓動耗時(s):"+((endTime-beginTime)/1000));
	}

	/**
	 * @Author wuxw
	 * @Description implements WebMvcConfigurer 該接口,重寫addResourceHandlers ,添加swagger2 UI doc樣式
	 * @Date 9:49 2019/3/15
	 * @Param [registry]
	 * @return void
	 **/
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

}

 默認UI界面

加強UI界面

其中, 展開頁籤功能 更是對開發者來講, 可隨意切換接口調試,很是的棒

 

推薦完畢

加強UI更多功能,歡迎訪問官方文檔

http://www.xiaominfo.com/swagger-bootstrap-ui/