springboot整合Swagger

本文主要講解springboot是如何經過整合Swagger-UI來實現一份至關完善的在線API文檔的。html

1. Swagger簡介

Swagger-UI是HTML, Javascript, CSS的一個集合,能夠動態地根據註解生成在線API文檔。java

經常使用註解

  • @Api:用於修飾Controller類,生成Controller相關文檔信息
  • @ApiOperation:用於修飾Controller類中的方法,生成接口方法相關文檔信息
  • @ApiParam:用於修飾接口中的參數,生成接口參數相關文檔信息
  • @ApiModelProperty:用於修飾實體類的屬性,當實體類是請求參數或返回結果時,直接生成相關文檔信息

2.整合Swagger-UI

2.1 添加項目依賴

在pom.xml文件中加入Swagger-UI相關依賴git

<!--  Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

 

2.2 添加Swagger-UI的配置

添加Swagger配置類Swagger2Configweb

package com.mzm.springboot.config;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {

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

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mzm.springboot.controller")) //爲當前包下controller生成API文檔
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //爲有@Api註解的Controller生成API文檔
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //爲有@ApiOperation註解的方法生成API文檔
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().
                title("測試Swagger2")
                .description("Spring Boot中使用Swagger2構建RESTful APIs")
                .version("1.0.0")
                .contact(new Contact("mzm", "https://gitee.com/moses_mao", "297531644@qq.com"))
                .build();
    }
}

 Swagger對生成API文檔的範圍有三種不一樣的選擇spring

  • 生成指定包下面的類的API文檔
  • 生成有指定註解的類的API文檔
  • 生成有指定註解的方法的API文檔

2.3 controller加入註解

package com.mzm.springboot.controller;

import com.mzm.springboot.controller.common.BaseController;
import com.mzm.springboot.exception.BusinessException;
import com.mzm.springboot.exception.EmBusinessError;
import com.mzm.springboot.response.CommonReturnType;
import com.mzm.springboot.service.UserSevice;
import com.mzm.springboot.service.model.UserModel;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


@Api(tags = "HomeController", description = "後臺首頁管理")
@RestController("user")
@RequestMapping("/user")
public class HomeController extends BaseController {

    @Autowired
    private UserSevice userSevice;

    @ApiOperation("hello word")
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String hello() {
        return "hello world";
    }

    @ApiOperation("獲取單個用戶")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public CommonReturnType getUser(@RequestParam(name = "id") Integer id) throws BusinessException {
        UserModel userModel = userSevice.getUserById(id);
        if (userModel == null) {
            throw new BusinessException(EmBusinessError.USER_NOT_EXISTS);
        }

        return CommonReturnType.create(userModel);
    }
}

 

3.查看結果

訪問Swagger-UI接口文檔地址

接口地址:http://localhost:8080/swagger-ui.htmlapi

相關文章
相關標籤/搜索