1.添加Swagger依赖jar包
| <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-annotations</artifactId> <version>${swagger.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>${jackson.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>${jackson.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>${jackson.version}</version> </dependency> |
| <swagger.version>1.5.10</swagger.version> <springfox.version>2.6.1</springfox.version> <jackson.version>2.8.8</jackson.version> |
2.引入Swagger配置类
| 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.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration @EnableWebMvc @EnableSwagger2 public class SwaggerConfig extends WebMvcConfigurerAdapter { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()).build().apiInfo(apiInfo()); }
private ApiInfo apiInfo() { ApiInfo apiInfo = new ApiInfoBuilder().title("Api Documentation").description("Api Documentation") .version("1.0").build(); return apiInfo; } } |
3.将SwaggerConfig注入到spring容器
| <bean id="swagger2Config" class="com.ocj.gtapi.common.adapter.SwaggerConfig" /> |
4.静态资源路径映射
| <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" /> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" /> |
5.Controller添加Swagger注解
| import javax.annotation.Resource;
import org.springframework.web.bind.annotation.PathVariable; 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.RestController;
import com.ocj.gtapi.web.demo1.model.User; import com.ocj.gtapi.web.demo1.service.DemoService;
import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam;
@Api(value = "用户", description = "用户相关接口") @RestController @RequestMapping("/User") public class DemoController {
@Resource DemoService demoService;
@ApiOperation(value = "新增用户", notes = "根据User对象创建用户", response = Integer.class) @ApiImplicitParam(name = "user", value = "用户实体对象", required = true, dataType = "User", paramType="body") @RequestMapping(value = "", method = RequestMethod.POST, produces = "application/json;charset=UTF-8") public Integer insertUser(@RequestBody User user) { return demoService.insertUserByUser(user); }
@ApiOperation(value = "删除用户", notes = "通过ID删除用户", response = Integer.class) @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType="path") @RequestMapping(value = "/{id}", method = RequestMethod.DELETE, produces = "text/html;charset=UTF-8") public Integer deleteUser( @PathVariable Integer id) { return demoService.deleteUserById(id); }
@ApiOperation(value = "更新用户", notes = "通过ID更新用户", response = Integer.class) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType="path"), @ApiImplicitParam(name = "user", value = "用户实体对象", required = true, dataType = "User", paramType="body") }) @RequestMapping(value = "/{id}", method = RequestMethod.PUT, produces = "application/json;charset=UTF-8") public Integer updateUser(@PathVariable Integer id, @RequestBody User user) { return demoService.updateUserById(id, user); }
@ApiOperation(value = "查询用户", notes = "通过ID查询用户", response = User.class) @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType="path") @RequestMapping(value = "/{id}", method = RequestMethod.GET, produces = "text/html;charset=UTF-8") public User selectUser(@PathVariable Integer id) { return demoService.selectUserById(id); }
} |
6.访问接口页面
| http://localhost:8080/swagger-ui.html |
7.Swagger汉化
找到/META-INF/resources/swagger-ui.html文件,增加下面配置
| <!--国际化操作：选择中文版 --> <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script> <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script> |
8.加强版汉化
找到/META-INF/resources/webjars/springfox-swagger-ui/lang/zh-cn.js文件,根据自己喜好设置
| 'use strict'; /* jshint quotmark: double */ window.SwaggerTranslator.learn({ "Warning: Deprecated":"警告：已过时", "Implementation Notes":"实现备注", "Response Class":"响应类", "Status":"状态", "Parameters":"参数", "Parameter":"参数", "Value":"值", "Description":"描述", "Parameter Type":"参数类型", "Data Type":"数据类型", "Response Messages":"响应消息", "HTTP Status Code":"HTTP状态码", "Reason":"原因", "Response Model":"响应模型", "Request URL":"请求URL", "Response Body":"响应体", "Response Code":"响应码", "Response Headers":"响应头", "Hide Response":"隐藏响应", "Headers":"头", "Try it out!":"试一下！", "Show/Hide":"显示/隐藏", "List Operations":"显示操作", "Expand Operations":"展开操作", "Raw":"原始", "can't parse JSON. Raw result":"无法解析JSON. 原始结果", "Example Value":"示例", "Click to set as parameter value":"点击设置参数", "Model Schema":"模型架构", "Model":"模型", "apply":"应用", "Username":"用户名", "Password":"密码", "Terms of service":"服务条款", "Created by":"创建者", "See more at":"查看更多：", "Contact the developer":"联系开发者", "api version":"api版本", "Response Content Type":"响应Content Type", "Parameter content type:":"参数类型:", "fetching resource":"正在获取资源", "fetching resource list":"正在获取资源列表", "Explore":"浏览", "Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis", "Can't read from server. It may not have the appropriate access-control-origin settings.":"无法从服务器读取。可能没有正确设置access-control-origin。", "Please specify the protocol for":"请指定协议：", "Can't read swagger JSON from":"无法读取swagger JSON于", "Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI", "Unable to read api":"无法读取api", "from path":"从路径", "server returned":"服务器返回" }); |