Swagger

最新推荐文章于 2022-09-14 13:29:49 发布

码仆的逆袭

最新推荐文章于 2022-09-14 13:29:49 发布

阅读量138

点赞数

分类专栏：开发工具文章标签： restful java spring boot

本文链接：https://blog.csdn.net/qq_34191426/article/details/119976761

版权

开发工具专栏收录该内容

9 篇文章 0 订阅

订阅专栏

Swagger

Swagger的作用

自动生成Java接口文档

Swagger工作流程

在这里插入图片描述

Springfox

Swagger Editor编写接口文档与传统式的编写接口文档没有区别，所以我们不用，我使用Springfox代替Swagger

优缺点

优点：
- 不再需要手动编写接口文档
- 修改代码后文档会自动更新
缺点：
- 代码侵入性强

依赖导入

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
	<exclusions>
		<exclusion>
			<artifactId>swagger-models</artifactId>
			<groupId>io.swagger</groupId>
		</exclusion>
		<exclusion>
			<artifactId>swagger-annotations</artifactId>
			<groupId>io.swagger</groupId>
		</exclusion>
	</exclusions>
</dependency>

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

配置Bean注入

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

	@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder().title("文档标题")
                        .version("版本号")
                        .contact(new Contact("作者名字","作者的个人网址","作者邮箱")).build())
                .select().apis(RequestHandlerSelectors.basePackage("cn.com.trueway")).build();
    }
}

controller层

注解：

Api：接口集合大标题
ApiOperation：每个接口的名称
ApiImplicitParam：一个参数的说明
- name ：参数名称
- value：参数说明
- required：是否必填
- example：举例
- defaultValue：默认值
ApiImplicitParams：ApiImplicitParam的集合

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/**
 * 用户
 */
@CrossOrigin(origins ="*",maxAge =3600)
@RestController
@RequestMapping("/user")
@Api(tags = "用户查询操作接口")
public class UserController {

    @Autowired
    private ElasticsearchRestTemplate elasticsearchRestTemplate;

    @Autowired
    private UserService userService;

    @Autowired
    private UserESDao userESDao;

    /**
     * 删除用户
     * @param userID
     * @return
     */
    @ApiOperation("删除用户")
    @ApiImplicitParam(name = "userID",value = "用户ID",required = true)
    @RequestMapping(value = "/delUser.do" , produces = "application/json;charset=utf-8" ,method = RequestMethod.POST)
    public Result delUser(String userID){
        if(Utils.isNotEmpty(userID)){
            Optional<UserModel> optional = userESDao.findById(userID);
            if(optional.isPresent()){
                try {
                    userESDao.deleteById(userID);
                    return new Result(RequestCode.SUCCESS,"删除成功！",true);
                } catch (Exception e) {
                    e.printStackTrace();
                    return new Result(RequestCode.ERROR,"删除失败，服务器异常！",false,e);
                }
            }else{
                return new Result(RequestCode.SUCCESS,"删除失败，删除数据不存在！",false);
            }
        }else{
            return new Result(RequestCode.SUCCESS,"参数不能为空！",false);
        }
    }

    /**
     * 查询用户
     * @param userName
     * @param account
     * @param startDay
     * @param endDay
     * @param startTime
     * @param endTime
     * @param page
     * @param limit
     * @return
     */
    @ApiOperation("查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName",value = "用户名称",required = false),
            @ApiImplicitParam(name = "account",value = "账号",required = false),
            @ApiImplicitParam(name = "startDay",value = "创建开始日期",required = false,example = "2021-01-01"),
            @ApiImplicitParam(name = "endDay",value = "创建结束日期",required = false,example = "2021-08-29"),
            @ApiImplicitParam(name = "startTime",value = "创建开始时段",required = false,example = "00:00:00"),
            @ApiImplicitParam(name = "endTime",value = "创建结束时段",required = false,example = "12:00:00"),
            @ApiImplicitParam(name = "page",value = "分页参数，默认1",required = false,defaultValue = "1"),
            @ApiImplicitParam(name = "limit",value = "分页参数，默认10",required = false,defaultValue = "10"),
    })
    @RequestMapping(value = "/queryUser.do" , produces = "application/json;charset=utf-8" ,method = RequestMethod.GET)
    public Result queryUser(String userName,String account,String startDay,String endDay,String startTime,String endTime,@RequestParam(defaultValue = "1") int page,@RequestParam(defaultValue = "10") int limit){
        try {
            //构建条件对象
            BoolQueryBuilder queryBuilder = new BoolQueryBuilder();
            //must必选查询，should选择性查询
            List<QueryBuilder> must = queryBuilder.must();
            if(Utils.isNotEmpty(userName)){
                //精准查询：matchQuery
                //模糊查询：matchPhrasePrefixQuery
                must.add(QueryBuilders.matchPhrasePrefixQuery("userName", userName));
            }
            if(Utils.isNotEmpty(account)){
                must.add(QueryBuilders.matchPhrasePrefixQuery("account",account));
            }
            if(Utils.isNotEmpty(startDay) && Utils.isNotEmpty(endDay)){
                must.add(QueryBuilders.rangeQuery("createTime").format("yyyy-MM-dd").gte(startDay).lte(endDay));
            }
            if(Utils.isNotEmpty(startTime) && Utils.isNotEmpty(endTime)){

                Map<String, Object> params = new HashMap<>();
                params.put("v0","createTime");
                params.put("v1","HH:mm:ss");
                params.put("v3",startTime);
                params.put("v7",endTime);
                must.add(QueryBuilders.scriptQuery(QueryBuilders.scriptQuery(new Script(Script.DEFAULT_SCRIPT_TYPE,Script.DEFAULT_SCRIPT_LANG,"InternalQlScriptUtils.nullSafeFilter(InternalQlScriptUtils.and(InternalQlScriptUtils.gte(InternalSqlScriptUtils.format(InternalQlScriptUtils.docValue(doc,params.v0),params.v1,'Z'), params.v3), InternalQlScriptUtils.lte(InternalSqlScriptUtils.format(InternalQlScriptUtils.docValue(doc,params.v0),params.v1,'Z'), params.v7)))",params)).script()));
            }

            NativeSearchQuery query = new NativeSearchQueryBuilder().withQuery(queryBuilder).withPageable(PageRequest.of((page - 1) * limit, limit, Sort.by(Sort.Direction.DESC, "createTime"))).build();
            System.out.println(query.getPreference());
            System.out.println(query.getQuery().toString());
            SearchHits<UserModel> hits = elasticsearchRestTemplate.search(query, UserModel.class);
            long total = hits.getTotalHits();
            List<UserModel> list = new ArrayList<>();
            hits.forEach(hit -> {
                list.add(hit.getContent());
            });
            return new Result(RequestCode.SUCCESS, "查询成功！", true,list,total);
        } catch (Exception e) {
            e.printStackTrace();
            return new Result(RequestCode.ERROR, "查询失败，服务器异常！", false,e);
        }
    }
}

model层

注解：

ApiModel
ApiModelProperty

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

@ApiModel("用户类")
@Data
@Document(indexName = "student_user",shards = 3,replicas = 1)
public class UserModel {

    @ApiModelProperty(value = "用户ID，系统生成")
    @Id
    private String userID;

    @ApiModelProperty(value = "用户名称")
    @Field(type = FieldType.Text)
    private String userName;

    @ApiModelProperty(value = "账号")
    @Field(type = FieldType.Text)
    private String account;

    @ApiModelProperty(value = "密码")
    @Field(type = FieldType.Keyword,index = false)
    private String password;

    @ApiModelProperty(value = "创建时间，系统生成")
    @Field(type = FieldType.Date,format = {},pattern = "yyyy-MM-dd HH:mm:ss")
    private String createTime;

    @ApiModelProperty(value = "写入时间，系统生成")
    @Field(type = FieldType.Date,format = {},pattern = "yyyy-MM-dd HH:mm:ss")
    private String writeTime;
}

拦截器过滤Swagger文档的拦截

import cn.com.trueway.interceptor.MyInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

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

@Configuration
public class WebMvcConfiguration implements WebMvcConfigurer {

    private static List<String> urlList = new ArrayList<String>();

    static{
        urlList.add("/doc.html");
        urlList.add("/webjars/**");
        urlList.add("/swagger-resources/*");
        urlList.add("/v2/**");
    }

    @Bean
    public MyInterceptor myInterceptor(){
        return new MyInterceptor();
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(myInterceptor()).addPathPatterns("/**").excludePathPatterns(urlList);
    }
}

Springmvc中过滤对Swagger的拦截

web.xml：

<servlet-mapping>
    <servlet-name>springmvc</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

<filter-mapping>
    <filter-name>encoding</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

springmvc.xml：

<mvc:resource location="/" mapping="/**"></mvc:resource>

请求地址

http://ip:port/projectName/swagger-ui.html

码仆的逆袭

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
复制链接

分享到 QQ

分享到新浪微博

扫一扫

专栏目录