在SpringBoot中使用Swagger2的步骤

Step1:在pom.xml中引用jar包

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

 

Step2：添加配置类

Swagger2Config.java

package com.example.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.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * Swagger2API文档的配置 
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger2 Test")
                .description("Swagger2 API docs")
                .version("1.0")
                .build();
    }

    private List<ApiKey> securitySchemes() {
        //设置请求头信息
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }

    private List<SecurityContext> securityContexts() {
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/admin/.*"));
//        result.add(getContextByPath("/product/.*")); 
        return result;
    }

    private SecurityContext getContextByPath(String pathRegex){
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }

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

 

Step3：给Application入口类加上 @EnableSwagger2 注解

 

Step4：给对应的Contoller和Action加注解。

（注意，RequestMapping要指定method，否则，文档生成时，会给全部的method类都生成说明。）

示例：

    @Controller
    @Api(tags = "PmsProductController", description = "商品管理")
    @RequestMapping("/product")
    public class PmsProductController {
        @Autowired
        private PmsProductService productService;

        @ApiOperation("创建商品")
        @RequestMapping(value = "/create", method = RequestMethod.POST)
        @ResponseBody 
        public CommonResult create(@RequestBody PmsProductParam productParam, BindingResult bindingResult) {
            int count = productService.create(productParam);
            if (count > 0) {
                return CommonResult.success(count);
            } else {
                return CommonResult.failed();
            }
        }
    }

 比较常用的注解：

1、@Api ：用于类
　　例：@Api(value="/admin",tags="管理员管理",description="说明描述")
2、@ApiOperation ：用于函数
　　例：@ApiOperation(value="修改",notes="修改会员姓名")
3、@ApiParam
　　例：@ApiParam(required=true,value="姓名")

 

Step5：启动项目，通过 http://localhost:端口/swagger-ui.html 查看文档