springBoot整合Swagger2

一 關於 Swagger

Swagger能成為最受歡迎的REST APIs文檔生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制台，開發者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK代碼用於各種不同的平台上的實現。
• Swagger 文件可以在許多不同的平台上從代碼注釋中自動生成。
• Swagger 有一個強大的社區，里面有許多強悍的貢獻者

二 Swagger的缺點

　　Swagger是一個非常強大的文檔工具,但是對代碼侵入性太高,這點等會截圖下來,大家就可以看到的,這個點是缺陷,也導致了很多公司並沒有使用他,當然使用他並沒有什么壞處

三:綜合分析swagger

　　在開發中我們構建RESTful風格Api時候就可能需要面對不同的開發前端,例如微信小程序,app,web,安卓,ios等,那么我們就需要一份開發文檔給前端人員進行調用,在之前筆者是采用showdoc進行構建的,就是石墨文檔,還有自己內部的服務器進行寫文檔的,這個給筆者開發帶了很大的麻煩,一個上午的時間只可以寫四個文檔,對每個參數進行說明,

　　同時,在開發過程中如果代碼修改,參數類型發生改變,還有請求類型發送改變,那么就需要去重新修改文檔,這個給開發效率造成了很大的麻煩,swagger是一個很好的開發工具,

 

四 springboot整合swagger

 　　1 pom.xml依賴引入

  <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
        </dependency>
<!--這個es的依賴是我整合時候es使用的,這個可以刪除,如果刪除就是需要練習者進行自己創建數據源 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

 

　　2 controller配置:

package com.cxy.es.controller;

import com.cxy.es.pojo.User;
import com.cxy.es.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.web.bind.annotation.*;
@Api(value="用戶controller",tags={"用戶操作接口"})
@RestController
@CrossOrigin
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserService userService;
    @ApiOperation(value="創建用戶", notes="根據User對象創建用戶")
    @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "User")
    @RequestMapping(value="",method=RequestMethod.POST)
    public String save(@RequestBody User user) {
        userService.save(user);
        return "a";
    }
    @ApiOperation(value="查詢user", notes="根據關鍵字查詢用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "keysword", value = "搜索關鍵字", required = false, dataType = "String"),
            @ApiImplicitParam(name = "page", value = "開始的頁數", required = true, dataType = "Integer"),
            @ApiImplicitParam(name = "size", value = "每頁的數量", required = true, dataType = "Integer")
    })
    @RequestMapping(value = "/get/{keysword}/{page}/{size}",method = RequestMethod.GET)
    public Page<User> findByUsernameOrTnameLike(@PathVariable String keysword,@PathVariable int page,@PathVariable int size){
        return userService.findByUsernameOrTnameLike(keysword,page,size);
    }
    @ApiOperation(value="查詢user", notes="根據關鍵字查詢用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "keysword", value = "搜索關鍵字", required = false, paramType="path",dataType = "String"),
            @ApiImplicitParam(name = "page", value = "開始的頁數", required = true,paramType="path", dataType = "Integer"),
            @ApiImplicitParam(name = "size", value = "每頁的數量", required = true,paramType="path", dataType = "Integer")
    })
    @RequestMapping(value = "/{keysword}/{page}/{size}",method = RequestMethod.GET)
    public Page<User> findByUsernameOrTnameLikeOOrderById(@PathVariable String keysword,@PathVariable int page,@PathVariable int size){
        return userService.findByUsernameOrTnameLikeOOrderById(keysword,page,size);
    }
}

此處數據方法對象,使用這應該進行修改,也可以直接返回一個數據即可

@ApiOperation

@ApiImplicitParams

@ApiImplicitParam

　　3 配置swagger

package com.cxy.es.config;

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
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cxy.es.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("項目使用")
                .termsOfServiceUrl("陳秀峰")
                .contact("陳秀峰")
                .version("1.0")
                .build();
    }

}

　　4 啟動

package com.cxy.es;


import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

public class EsApplication {

    public static void main(String[] args) {
        SpringApplication.run(EsApplication.class, args);
    }

}

 

然后再在瀏覽器輸入:
http://localhost:8009/swagger-ui.html#/

點擊用戶controller之后就可以看到所寫的接口

 

注意事項看截圖:

 坑1

 

 坑2