效果图
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
二：使用方法一：使用第三方依赖（最简单的方法）
1、在pom.xml文件中添加第三方swagger依赖（）
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目，里面有详细的讲解。
方法二：使用官方依赖+配置类
1、在pom.xml文件中添加swagger相关依赖
<!-- swagger-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。
2、 开启启动类application@EnableSwagger2 或者在3中直接填写
3、swagger的configuration
需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。
package com.bennyrhys.mall.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@Configuration
public class SpringFoxConfig {
//访问http://localhost:8080/swagger-ui.html可以看到API文档
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any()) // .apis(RequestHandlerSelectors.basePackage("com.bennyrhys.swagger"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("慕慕生鲜")
.description("详细描述")
.contact(new Contact("bennyrhys", "htpps://xxx", "bennyrhys@163.com"))
// .version("v1.0.0")
.license("v1.0.0-Apache2.0")
.termsOfServiceUrl("")
.build();
}
}
4、可选地址映射
package com.bennyrhys.mall.config;
import com.bennyrhys.mall.comm.Constant;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* 描述： 配置地址映射
*/
@Configuration
public class MallWebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// registry.addResourceHandler("/admin/**").addResourceLocations("classpath:/static/admin/");
// registry.addResourceHandler("/images/**")
// .addResourceLocations("file:" + Constant.FILE_UPLOAD_DIR);
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
实体类
描述、必填、隐藏
2.x版本
/**
* @Author bennyrhys
*/
@ApiModel(description = "用户信息描述类")
public class User {
@ApiModelProperty(value = "用户id")
private Integer id;
@ApiModelProperty(value = "用户名")
private String username;
@ApiModelProperty(value = "用户地址")
private String address;
1.x版本
@ApiModelProperty(value = "Topic列表", required = false, hidden = true)
controller
建议不加value
加operation的描述方法
加是否必传
// 可以不展示此接口
// @ApiIgnore
查询，是否必要
/**
* 查询用户 【页面参数query】
* @param id
* @return
*/
// 方法 方法描述
@ApiOperation(value = "查询用户",notes = "根据用户id查询用户 ")
// 参数 参数描述 参数必填【针对swagger】
// @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
@GetMapping("/user")
public User getUserById(Integer id) {
User user = new User();
user.setId(id);
return user;
}
删除，返回值
@ApiOperation(value = "删除用户",notes = "根据用户id删除用户")
@ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
@ApiResponses({
@ApiResponse(code = 200, message = "删除成功"),
@ApiResponse(code = 500, message = "删除失败")
})
更新，多参数
/**
* 更新用户
*/
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99"),
@ApiImplicitParam(name = "username", value = "用户名", required = true, defaultValue = "bennyrhys")
})
@ApiOperation(value = "更新用户",notes = "根据用户id更新用户名")
权限
响应
