springboot集成swagger2

1. 關於Swagger

Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

相信採用 Spring Boot 開發的小夥伴幾乎是用來構建 RESTful API ，而文檔天然是不可缺乏的一部分，Swagger 的出現，既能夠減小咱們建立文檔的工做量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。

另外Swagger2也提供了強大的頁面測試功能來調試每一個RESTful API。

做用總結：

• 接口文檔在線生成
• 方便功能測試

集成後的效果圖以下：

2. 開始集成

2.1 添加依賴

在 pom.xml 中添加 swagger 依賴

<!-- Swagger API文檔 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

2.2 配置Swagger

applicaton.yml

# Swagger界面內容配置
swagger:
  title: TMax API接口文檔
  description: TMax Api Documentation
  version: 1.0.0
  termsOfServiceUrl: https://www.sscai.club
  contact:
    name: niceyoo
    url: https://www.sscai.club
    email: apkdream@163.com

如上配置請置於根節點，以下圖所示：

Swagger2Config.java

新建一個 Swagger2Config.java 的配置類：

1. 添加 @Configuration 註解，用於定義配置類，方便被Spring Boot配置；
2. 添加 @EnableSwagger2 註解啓動 Swagger 文檔構建能力。

完整代碼以下：

@Slf4j
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.title}")
    private String title;

    @Value("${swagger.description}")
    private String description;

    @Value("${swagger.version}")
    private String version;

    @Value("${swagger.termsOfServiceUrl}")
    private String termsOfServiceUrl;

    @Value("${swagger.contact.name}")
    private String name;

    @Value("${swagger.contact.url}")
    private String url;

    @Value("${swagger.contact.email}")
    private String email;

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("Authorization", "accessToken", "header"));
        return apiKeys;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    @Bean
    public Docket createRestApi() {

        log.info("加載Swagger2");

        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).select()
            ## 掃描全部有註解的api，用這種方式更靈活
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(name, url, email))
                .version(version)
                .build();
    }
}

方法講解：

經過 createRestfulApiDocs() 方法建立 Docket 的 Bean 以後，apiInfo() 用來建立該 API 的基本信息。（這些基本信息會展示在文檔頁面中，如最開始的預覽圖，增長一些文檔自定義信息）

select() 函數返回一個 ApiSelectorBuilder 實例用來控制哪些接口暴露給Swagger 來展示，本例採用掃描全部帶有 API 註解的對外開放，同時，你也能夠採用指定掃描的包路徑來定義，Swagger 則會掃描該包下全部 Controller定義的 API，併產生文檔內容（除了被@ApiIgnore指定的請求）。

若是採用掃描指定包路徑的話，須要修改 createRestApi() 方法的 apis 部分：

.apis(RequestHandlerSelectors.basePackage("com.lemon.security.web.controller"))

2.3 新建entity和controller測試

entity：VideoCategory.java

@Data
@Entity
@Table(name = "v_category")
@TableName("v_category")
@ApiModel(value = "視頻類型")
public class VideoCategory extends TmaxBaseEntity {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "類型名稱")
    private String title;

    @ApiModelProperty(value = "排序值")
    @Column(precision = 10, scale = 2)
    private BigDecimal sortOrder;

    @ApiModelProperty(value = "是否啓用 0啓用 -1禁用")
    private Integer status = CommonConstant.STATUS_NORMAL;

}

controller：VideoCategoryController 主要以添加、查詢爲例

@Slf4j
@RestController
@Api(description = "視頻類型管理接口")
@RequestMapping("/tmax/videoCategory")
@Transactional
public class VideoCategoryController extends TmaxBaseController<VideoCategory, String> {

    @Autowired
    private VideoCategoryService videoCategoryService;

    @Override
    public VideoCategoryService getService() {
        return videoCategoryService;
    }

    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ApiOperation(value = "添加")
    public Result<Object> add(@ModelAttribute VideoCategory videoCategory){

        VideoCategory d = videoCategoryService.save(videoCategory);
        return new ResultUtil<Object>().setSuccessMsg("添加成功");
    }

    @RequestMapping(value = "/search", method = RequestMethod.GET)
    @ApiOperation(value = "分類名模糊搜索")
    public Result<List<VideoCategory>> searchByTitle(
            @RequestParam String title,
            @ApiParam("是否開始數據權限過濾") @RequestParam(required = false, defaultValue = "true") Boolean openDataFilter){

        List<VideoCategory> list = videoCategoryService.findByTitleLikeOrderBySortOrder("%"+title+"%", openDataFilter);
        return new ResultUtil<List<VideoCategory>>().setData(list);
    }

}

經常使用註解說明：

• @Api()用於類；
  表示標識這個類是swagger的資源
• @ApiOperation()用於方法；
  表示一個http請求的操做
• @ApiParam()用於方法，參數，字段說明；
  表示對參數的添加元數據（說明或是否必填等）
• @ApiModel()用於類
  表示對類進行說明，用於參數用實體類接收
• @ApiModelProperty()用於方法，字段
  表示對model屬性的說明或者數據操做更改
• @ApiIgnore()用於類，方法，方法參數
  表示這個方法或者類被忽略
• @ApiImplicitParam() 用於方法
  表示單獨的請求參數
• @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

項目啓動後訪問：http://localhost:端口號(例如8080)/swagger-ui.html

咱們嘗試操做一下 add() 方法：

1. 填寫實體基本信息
2. 點擊 Try it out! 按鈕

3. 最後

在上邊的整個過程當中，咱們瞭解 Swagger 除了查看接口功能外，還提供了調試測試功能，點擊「Try it out！」按鈕，便可完成了一次請求調用！

此時，你也能夠經過幾個 POST 請求來驗證以前的 POST 請求是否正確。相比爲這些接口編寫文檔的工做，咱們增長的配置內容是很是少並且精簡的，對於原有代碼的侵入也在忍受範圍以內。

所以，在構建 RESTful API 的同時，加入 Swagger 來對 API 文檔進行管理，是個不錯的選擇。