swagger接口文档的简单配置

爱上编程2705

已于 2022-07-14 16:16:16 修改

阅读量1.1k

点赞数

分类专栏： spring-boot框架基础配置 spring-cloud基础架构文章标签： swagger2

于 2021-04-14 14:31:12 首次发布

本文链接：https://blog.csdn.net/L1569850979/article/details/115697560

版权

spring-cloud基础架构同时被 2 个专栏收录

22 篇文章 1 订阅

订阅专栏

spring-boot框架基础配置

19 篇文章 0 订阅

订阅专栏

swagger接口文档的简单配置

jar包的引入

    <properties>
		<java.version>1.8</java.version>
		<springfox-swagger.version>2.8.0</springfox-swagger.version>
		<swagger-bootstrap-ui.version>1.9.6</swagger-bootstrap-ui.version>
	</properties>
	
	<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>${springfox-swagger.version}</version>
		</dependency>


		<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>swagger-bootstrap-ui</artifactId>
			<version>${swagger-bootstrap-ui.version}</version>
		</dependency>

2.swagger配置

package com.example.demo.commons;

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.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 SwaggerConfig {

    @Bean
    public Docket petApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo")) //指定提供接口所在的基包
                .build();
    }

    /**
     * 该套 API 说明，包含作者、简介、版本、host、服务URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("v1.0") 
                .contact(new Contact("Llc","null","https://blog.csdn.net/L1569850979?spm=1010.2135.3001.5113"))
                .version("0.1")
                .termsOfServiceUrl("http://localhost:8080/doc.html")
                .description("版本测试swagger")
                .build();
    }

}

3.controller层代码演示

@Slf4j
@RestController
@RequestMapping("/one")
@Api(value = "测试",tags = "控制器二")
public class TestOneContoller {



    @GetMapping(value ="/getUserName")
    @ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
    @ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
    public String getUserName(@RequestParam Integer userNumber){
        log.info("测试你好:{}",userNumber);
        if(userNumber == 1){
            return "张三丰";
        }
        else if(userNumber == 2){
            return "慕容复";
        }
        else{
            return "未知";
        }

    }

    @GetMapping("/updatePassword")
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
    })
    public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
                                 @RequestParam(value="newPassword") String newPassword){
        if(userId <= 0 || userId > 2){
            return "未知的用户";
        }
        if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
            return "密码不能为空";
        }
        if(password.equals(newPassword)){
            return "新旧密码不能相同";
        }
        return "密码修改成功!";
    }

4.swagger的相关注解

1、swagger2 注解整体说明

用于controller类上：

注解说明
@Api 对请求类的说明
用于方法上面（说明参数的含义）：

注解说明
@ApiOperation 方法的说明
@ApiImplicitParams、@ApiImplicitParam 方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
用于方法上面（返回参数或对象的说明）：

注解说明
@ApiResponses、@ApiResponse 方法返回值的说明；@ApiResponses 用于指定单个参数的说明
对象类：

注解说明
@ApiModel 用在JavaBean类上，说明JavaBean的用途
@ApiModelProperty 用在JavaBean类的属性上面，说明此属性的的含议

2、@Api：请求类的说明

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
	tags="说明该类的作用"
	value="该参数没什么意义，所以不需要配置"

示例：

@Slf4j
@RestController
@RequestMapping("/one")
@Api(value = "测试",tags = "控制器二")
public class TestOneContoller {
}

3.实体类的简单注解

@Data
@ApiModel
public class AddAnchorDTO {

    @ApiModelProperty(value = "微信号")
    @NotNull(message = "微信号不能为空")
    @Pattern(regexp = Validator.WE_CHAT_NUM, message = "微信号格式不正确")
    private String weChat;

    @ApiModelProperty(value = "主播昵称")
    @NotNull(message = "主播昵称不能为空")
    @Length(min = 2, max = 15, message = "主播昵称长度不符合要求")
    private String anchorNickName;

    @ApiModelProperty(value = "真实姓名")
    @NotNull(message = "真实姓名不能为空")
    @Length(min = 2, message = "真实姓名长度不符合要求")
    private String realName;

    @ApiModelProperty(value = "身份证号")
    @NotNull(message = "身份证号不能为空")
    @Pattern(regexp = Validator.REGEX_ID_CARD, message = "身份证号格式不正确")
    private String idCardNumber;

    @ApiModelProperty(value = "身份证正面照片")
    @NotNull(message = "身份证正面照片不能为空")
    private String cardFrontPhoto;

    @ApiModelProperty(value = "身份证背面照片")
    @NotNull(message = "身份证背面照片不能为空")
    private String cardBackPhoto;

    @ApiModelProperty(value = "本人正面照片")
    @NotNull(message = "本人正面照片不能为空")
    private String facePhoto;

    @ApiModelProperty(value = "联系电话")
    @NotNull(message = "联系电话不能为空")
    @Pattern(regexp = Validator.REGEX_MOBILE, message = "手机号格式不正确")
    private String phone;

}

配置完成后访问：http://localhost:8080/doc.html

在这里插入图片描述
备注：swagger-bootstrap-ui的版本不同，swagger中的样式可能会改变

Swagger2的配置接口文档的简单配置

导入jar包

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
        <!-- swagger2 依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

需要放行的路径

"/doc.html",
"/webjars/**",
"/swagger-resources/**",
"/v2/api-docs/**"

配置文件的编写

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包下的controller生成api文档
                .apis(RequestHandlerSelectors.basePackage("icu.lijiaqi.server.controller"))
                .paths(PathSelectors.any())
                .build()
                .securityContexts(securityContexts())
                .securitySchemes(securitySchemes());
    }
    private ApiInfo apiInfo() {
        //设置文档信息
        return new ApiInfoBuilder()
                .title("小7云E办接口文档")
                .description("小7云E办接口文档")
                .contact(new Contact("李佳琪", "http:localhost:8081/doc.html",
                        "1004102689@qq.com"))
                .version("1.0")
                .build();
    }
    public List<SecurityContext> securityContexts(){
        //认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/hello/.*"));
        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;
    }
 
    public List<ApiKey> securitySchemes(){
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization","Authorization","Header");
        result.add(apiKey);
        return result;
    }
 
}

当spring boot与swagger的版本不匹配的时候会报如下错误
在这里插入图片描述
解决方法：
在配置文件中配置

    mvc:
        pathmatch:
            matching-strategy: ant_path_matcher

在这里插入图片描述

爱上编程2705

关注

0
点赞
踩
1

收藏

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

分享到 QQ

分享到新浪微博

扫一扫

专栏目录