使用Swagger编写Api接口文档

1、导入SwaggerJar包(最新版2.9.2)
<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>
2、编写SwaggerConfig配置:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select().build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("学习Swagger")
                .description("API接口说明文档")
                .version("1.0-Beta")
                .termsOfServiceUrl("https://www.码农老中医.com")
                .contact(new Contact("码农老中医", "https://www.码农老中医.com", null))
                .license("https://www.码农老中医.com")
                .licenseUrl("https://www.码农老中医.com")
                .build();
    }

}
  • 创建一个Maven项目导入Swagger相关的Jar包,启动项目浏览器地址输入http://localhost:8080/swagger-ui.html如图所示:

swagger接口文档
简单的Swagger就配置完成了,在apiInfo()这个方法里面,参数很多,其实没有必须要配置完全,把重要的信息配置上即可,在这个只是一个案例。

  • 使用RequestHandlerSelectors方法来设置Swagger扫描接口:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.any()).build()
               ;
   }

}
RequestHandlerSelectors方法中有5个参数:
	any:默认扫描所有接口
	none:不扫描
	basePackage:按照包扫描
	withClassAnnotation:扫描类上的注解
	withMethodAnnotation:扫描方法上的注解
  • 使用PathSelectors方法过滤接口:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.swagger.controller"))
                // 只需要hello下面的所有请求。
                .paths(PathSelectors.ant("/hello/**"))
                .build()
                ;
    }

}
PathSelectors方法中有4个参数:
	ant:通过表达式
	any:默认扫描所有接口
	none:不扫描
	regex:用正则表达式来判断,true = 扫描 / false 不扫描
  • 使用ignoredParameterTypes配置接口忽略参数:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		// 接口中所有Integer类型的参数,全部忽略。
                .ignoredParameterTypes(Integer.class)
                ;
    }

}
  • 在不同的环境下配置是否启动Swagger:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    Environment environment;

    @Bean
    public Docket createRestApi() {
        Profiles profiles = Profiles.of("dev", "test");
        boolean isEnable = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isEnable)
                ;
    }

}
enable()方法返回一个boolean类型的值,默认为true,false时不可访问。
在resources新建4个配置文件为:

application.yml:
spring:
  profiles:
    active: prod

application-dev.yml:开发环境

application-prod.yml:生产环境

application-test.yml:测试环境
  • API接口分组:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docketUser() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户")
                .select().paths(PathSelectors.ant("/user")).build();
    }

    @Bean
    public Docket docketHello() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("你好")
                .select().paths(PathSelectors.ant("/hello")).build();
    }

}

分组信息

  • 展示实体类:
@ApiOperation("添加用户信息")
@PostMapping
public User insertUser(User users) {
    return users;
}
@Data
@AllArgsConstructor
@ApiModel("用户实体类")
public class User implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("年龄")
    private Integer age;

}
@ApiModelProperty(value = "参数说明", name = "参数", required = 是否必传,example="示例")

在这里插入图片描述
在这里插入图片描述

  • 配置全局参数:
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket() {
        Parameter token = new ParameterBuilder().name("token")
                .description("用户登录令牌")
                .parameterType("header")
                .modelRef(new ModelRef("String"))
                .required(true)
                .build();
        List<Parameter> parameter = new ArrayList<>();
        parameter.add(token);
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(parameter);
    }

}
  • 使用@Api注解和@ApiOperation注解说明:
@Api(tags = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping
    public String getUser() {
        return "users";
    }

}
@Api:在类上使用

@ApiOperation:在方法上使用

在这里插入图片描述

  • 使用@ApiImplicitParams或@ApiImplicitParam配置接口参数说明:
@Api(tags = "用户信息")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("获取用户信息")
    @ApiImplicitParams(
            {
                    @ApiImplicitParam(name = "username", value = "用户名",defaultValue = "张三",example = "lisi",required = true),
                    @ApiImplicitParam(name = "username", value = "密码", required = true)
            }
    )
    @GetMapping
    public String getUser(String username, String password) {
        return "users";
    }

}

在这里插入图片描述

在查看接口时 defaultValue 的值会显示出来 
点击 Try it out 以后 example 的值才会显示

在这里插入图片描述

  • 多个参数写法:
@ApiImplicitParams({
	@ApiImplicitParam(参数1),
	@ApiImplicitParam(参数1),
	@ApiImplicitParam(参数1)
})

如果真的是接收多个参数,最好用实体类去接收。

  • 一个参数写法:
@ApiImplicitParam(参数)
  • 解决java.lang.NumberFormatException: For input string: ""错误:

错误案例

  • 第一种解决方法:
在实体类中用@ApiModelProperty注解时加上example
  • 第二种解决方法:
Jar包版本:
<swagger2.version>2.9.2</swagger2.version>
<swagger.version>1.5.22</swagger.version>

步骤一:先把swagger2中的annotations和models排除掉
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger2.version}</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
        </exclusion>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger2.version}</version>
</dependency>

步骤二:自己引入annotations和models Jar包信息
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>${swagger.version}</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>${swagger.version}</version>
</dependency>

注:有可能只需要排除models即可。

这个是没有排除时报错的地方。
在这里插入图片描述
引入1.5.22版本的,再去查看之前报错的地方。
在这里插入图片描述
在这里插入图片描述

  • 1
    点赞
  • 9
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值