swagger简介
- 简介：Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
- 作用:
- 接口的文档在线自动生成。
- 功能测试。
使用的时候注意版本问题，以及整合springSecurity时要开放相关的接口
相关的依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
注意版本!!!!
注意版本!!!!
注意版本!!!!
高本版的使用下述代码可能生成的有问题
相关代码
配置类
package com.mao.swagger.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author dgh
* @date 18-11-15 下午8:33
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket swaggerSpringMvcPlugin() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
}
}
配置类(详细)
GITHUB使用的是上面的配置类作为演示
package group.uchain.project_management_system.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfiguration implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Bean
public Docket createRestApi() {
//添加head参数start
ParameterBuilder token = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
token.name("Authorization").description("token")
.modelRef(new ModelRef("string")).parameterType("header")
.required(false).build();
//根据每个方法名也知道当前方法在设置什么参数
pars.add(token.build());
//添加head参数end
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//指定接口的位置
.apis(RequestHandlerSelectors.basePackage("group.uchain.project_management_system.controller"))
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("项目管理系统")
.description("API交互接口")
.termsOfServiceUrl("")
.version("1.0")
.build();
}
}
Controller
package com.mao.swagger.controller;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.mao.swagger.beans.ResObject;
import com.mao.swagger.beans.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
/**
* @author dgh
* @date 18-11-15 下午8:35
*/
@Api(description = "用户接口")
@RestController
@RequestMapping("/demo")
public class MyController {
@ApiOperation(value = "用户名",notes = "新增注册")
@RequestMapping(value="/createUser",method= RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
public ResObject createUser(@RequestBody User user){
System.out.println("createUser:::"+user.toString());
return new ResObject(HttpStatus.OK.value(), "新增成功.");
}
@ApiOperation(value = "修改用户" , notes="修改用户")
@RequestMapping(value="/updateUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
public ResObject updateUser(@RequestBody User user){
System.out.println("updateUser:::"+user.toString());
return new ResObject(HttpStatus.OK.value(), "修改成功.");
}
@ApiOperation(value = "删除用户" , notes="删除用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value="/deleteUser",method=RequestMethod.DELETE)
public ResObject deleteUser(@RequestParam("userId") String userId){
System.out.println("deleteUser:::"+userId);
return new ResObject(HttpStatus.OK.value(), "删除成功.");
}
@ApiOperation(value = "查询用户" , notes="查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value="/queryUser",method=RequestMethod.GET)
public ResObject queryUser(@RequestParam("userId") String userId){
System.out.println("queryUser:::"+userId);
User user = new User(userId, "张三", "******", "mao2080@sina.com");
return new ResObject(HttpStatus.OK.value(), user);
}
}
效果展示
按照上面的启动之后访问：http://localhost:8080/swagger-ui.html
这里的话就可以自己对照上_面的代码进行匹配
有问题欢迎交流
GitHub源码:https://github.com/Panghu98/swagger
更多关于swaggerhttps://swagger.io/tools/swagger-ui/
