Swagger——springBoot整合Swagger组件生成接口文档

项目开发中，前后端分离时，进行接口对接工作需要接口文档。

因此选择了Swagger替代手动写接口文档的工作。

Swagger的注释说明，参考原文链接https://blog.csdn.net/xiaojin21cen/article/details/78654652

 

 

maven添加swagger依赖

            <!-- swagger -->
            <dependency>
	        <groupId>io.springfox</groupId>
	        <artifactId>springfox-swagger2</artifactId>
	        <version>2.9.2</version>
	    </dependency>
	    <dependency>
	        <groupId>io.springfox</groupId>
	        <artifactId>springfox-swagger-ui</artifactId>
	        <version>2.9.2</version>
	    </dependency>
	    <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

看好自己swagger版本与jdk版本的关系了。版本表转自https://blog.csdn.net/qq_26264237/article/details/90578847

 

添加依赖包后，加入配置

import io.swagger.annotations.Api;

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

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Value("${swagger2.enable}")
	private Boolean enable = false; 
	
    @Bean
    public Docket createRestApi() {
    	//pars用来统一一些公用参数，这里设置前端和后台登录的输入参数
        List<Parameter> pars = new ArrayList<Parameter>();
    	ParameterBuilder tokenPar2 = new ParameterBuilder();
        tokenPar2.name("sessionId")
                .description("登录令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")  //参数类型为header中的参数
                .required(false)
                .build();
 
        ParameterBuilder tokenPar = new ParameterBuilder();
        tokenPar.name("Authorization")
                .description("后台登录令牌(token)")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .required(false)
                .build();
 
        //看项目情况需不需要添加固定的表头参数,可add多个
        pars.add(tokenPar.build());
        pars.add(tokenPar2.build());
    	
        return new Docket(DocumentationType.SWAGGER_2)
        		.globalOperationParameters(pars)//定义全局的请求参数，不需就去掉
                .apiInfo(apiInfo())
                .enable(enable)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//这是注意的代码
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("demo接口文档")//整个swagger文档的大标题
                .description("demo相关接口的文档")//swagger的详细描述
                .termsOfServiceUrl("http://localhost:6001/sys")//该项目的地址
                .version("1.0")//版本号
                .build();
    }

}

 

然后是controller的@Api、方法的@ApiOperation、属性的@ApiModelProperty这三个主要的添加注释。注解还有很多属性值可以设置。

Controller的

@Api(tags = "TestController", description = "测试模块")
@RestController
public class test(){}

方法的

@ApiOperation(value="测试方法", notes = "测试方法的详细描述……")
@RequestMapping(value = "/test", method = RequestMethod.POST)
public void test(){}

属性的

public class TestDto {

    @ApiModelProperty(value = "用户名称",required = true)
    private String userName;
    @ApiModelProperty(value = "账号",readOnly = true)
    private String account;
    @ApiModelProperty(value = "密码",hidden = true)
    private String password;
    @ApiModelProperty(value = "创建人")
    private String createUser;

    //get，set略

}