swagger2 入門教程

swagger2 是一個規范和完整的框架，用於生成、描述、調用和可視化Restful風格的web服務，現在我們使用spring boot 整合它

 

作用：

1、接口的文檔在線自動生成

2、功能測試

 

先介紹它的常用注解

@Api  注解可以用來標記 Controller 的功能

@ApiOperation 注解用來標記一個方法的作用

@ApilmplicitParam 注解用來描述一個參數，可以配置參數的中文含義，也可以給參數設置默認值，這樣在接口測試的時候可以避免手動輸入

@ApilmplicitParams 如果有多個參數，則需要使用多個 @ApilmplicitParam 注解來描述， 多個 @ApilmplicitParam 注解需要放在一個 @ApilmplicitParams 注解中

@ApiModel  如果參數是一個對象，則需要在對象所在的類上加上此注解

@ApiModelProperty  如果參數是一個對象，則需要在對應的屬性上加上此注解，還需要在對象所在的類上加上 @ApiModel

@ApiIgnore 注解標識此參數可以忽略

 

下面介紹它的使用

 

1、引入它的依賴

<!--寫接口文檔的api-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <artifactId>guava</artifactId>
                    <groupId>com.google.guava</groupId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${guava.version}</version>
        </dependency>
        <!--界面支持-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

 

2、使用開啟注解 @EnableSwagger2 和 配置映射路徑、要掃描的接口的未知、文檔網站信息

package io.xiongdi.config;

import io.swagger.annotations.ApiOperation;
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.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @author wujiaxing
 * <p>
 * 使用Swagger2只需三步
 * 1、導入Swaggerr依賴
 * 2、配置Docket的bean
 * 3、使用@Api等注解修飾
 * </p>
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 方法需要有ApiOperation注解才能生存接口文檔
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路徑使用any風格
                .paths(PathSelectors.any())
                .build()
                // 如何保護我們的Api，有三種驗證（ApiKey, BasicAuth, OAuth）
                .securitySchemes(security())
                // 接口文檔的基本信息
                .apiInfo(apiInfo());
    }

    /**
     * 接口文檔詳細信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("兄弟足浴").description("xd-api文檔").termsOfServiceUrl("http://www.localhost:8002").version("1.0.0").build();
    }

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

 

3、使用它的注解標識要創建的接口文檔

package io.xiongdi.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.xiongdi.annotation.Login;
import io.xiongdi.common.utils.R;
import io.xiongdi.common.validator.ValidatorUtils;
import io.xiongdi.form.LoginForm;
import io.xiongdi.service.TokenService;
import io.xiongdi.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.Map;

/**
 * @author wujiaxing
 * @date 2019-07-07
 */
@Api(tags = "登錄接口")
@RequestMapping("/api")
@RestController
public class ApiLoginController {

    @Autowired
    private TokenService tokenService;
    @Autowired
    private UserService userService;

    @RequestMapping("login")
    @ApiOperation("登錄")
    public R login(@RequestBody  LoginForm loginForm) {
        // 服務端表單校驗
        System.out.println("已進入login"+loginForm);
        ValidatorUtils.validateEntity(loginForm);
        // 執行登錄
        Map<String, Object> map = userService.login(loginForm);

        return R.ok(map);
    }

    /**
     * <p>
     *     登出需要請求中帶token
     *     @RequestAttribute 這個注解表示訪問有過濾器或攔截器創建的、預先存在的屬性
     * </p>
     * @param userId
     * @return
     */
    @Login
    @ApiOperation("登出")
    @RequestMapping("logout")
    public R logout(@RequestAttribute("userId") @ApiIgnore long userId) {
        tokenService.expireToken(userId);
        return R.ok();
    }
}

package io.xiongdi.form;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;

/**
 * 登錄表單
 * @author wujiaxing
 * @date 2019-06-30
 */
@Data
@ApiModel(value = "登錄表單")
public class LoginForm {

    @ApiModelProperty(value = "手機號")
    @NotBlank(message = "手機號不能為空")
    private String mobile;

    @ApiModelProperty(value = "密碼")
    @NotBlank(message = "密碼不能為空")
    private String password;
}

 

4、正常來說，配置以上三步就可以了，但如果配置了跨域，則需要配置靜態資源放過

package io.xiongdi.config;

import io.xiongdi.interceptor.AuthorizationInterceptor;
import io.xiongdi.resolver.LoginUserHandlerMethodArgumentResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.List;

/**
 * @author wujiaxing
 * <p>
 *     此配置類可配置攔截器、參數解析器、返回值解析器、跨域支持等等
 * </p>
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private AuthorizationInterceptor authorizationInterceptor;
    @Autowired
    private LoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver;

    /**
     *  如果配置跨域，就增加這個配置
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("/static/");
        registry.addResourceHandler("/js/**").addResourceLocations("/js/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");
    }

    /**
     * 攔截器配置
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**");
    }

    /**
     * 跨域支持配置
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600);
    }

    /**
     * 參數解析配置
     * @param resolvers
     */
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(loginUserHandlerMethodArgumentResolver);
    }
}

 

至此基本配置已完成，訪問 localhost:8080/swagger-ui.html