简介
swagger是一个流行的API开发框架,这个框架以“开放API声明”(OpenAPI Specification,OAS)为基础, 对整个API的开发周期都提供了相应的解决方案,是一个非常庞大的项目(包括设计、编码和测试,几乎支持所有语言)。
springfox大致原理:
springfox的大致原理就是,在项目启动的过种中,spring上下文在初始化的过程, 框架自动跟据配置加载一些swagger相关的bean到当前的上下文中,并自动扫描系统中可能需要生成api文档那些类, 并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类,并生成对应的文档描述数据.该数据是json格式,通过路径:项目地址/ v2/api-docs可以访问到该数据,然后swaggerUI根据这份数据生成相应的文档描述界面。 因为我们能拿到这份数据,所以我们也可以生成自己的页面.
SpringBoot整合Swagger2
引入依赖
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger2</artifactId>
- <version>2.7.0</version>
- </dependency>
- <dependency>
- <groupId>io.springfox</groupId>
- <artifactId>springfox-swagger-ui</artifactId>
- <version>2.7.0</version>
- </dependency>
注意:jdk1.8以上才能运行swagger2
编写配置类配置Swagger
- @Configuration
- @EnableSwagger2
- public class SwaggerConfig{
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo())
- .select()
- .apis(RequestHandlerSelectors.basePackage("org.example.yourproject"))//这里填写项目package
- .paths(PathSelectors.any())
- .build();
- }//springfox为我们提供了一个Docket(摘要的意思)类,我们需要把它做成一个Bean注入到spring中, 显然,我们需要一个配置文件,并通过一种方式(显然它会是一个注解)告诉程序,这是一个Swagger配置文件。
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("Spring Boot中使用Swagger2构建RESTful API")
- .description("rest api 文档构建利器")
- .termsOfServiceUrl("https://www.cnblogs.com/yrxing/")
- .contact("xing")
- .version("1.0")
- .build();
- }
- }//springfox允许我们将信息组合成一个ApiInfo的类,作为构造参数传给Docket
访问:http://localhost:{your_server_port}/swagger-ui.html
Swagger2常用注解使用
@Api()、@ApiOperation()
- @RestController
- @RequestMapping(value = "/user", produces = APPLICATION_JSON_VALUE) //配置返回值 application/json
- @Api(tags = "用户管理")
- public class HelloController {
- ArrayList<User> users = new ArrayList<>();
- @ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
- @RequestMapping(value = {""}, method = RequestMethod.GET)
- public List<User> hello() {
- users.add(new User("逻辑", "luoji"));
- users.add(new User("叶文杰", "yewenjie"));
- return users;
- }
- }
@ApiModel()、@ApiModelProperty()
- @ApiModel(description = "用户",value = "用户")
- public class User {
- private String id;
- @ApiModelProperty(value = "用户名")//value属性指明了该字段的含义(描述 Description)
- private String username;
- @ApiModelProperty(hidden = true)//此注解可以作用在字段或者方法上,只要 hidden 属性为 true ,该字段或者方法就不会被生成api文档.
- private String password;
- private String email;
- private Integer age;
- private Boolean enabled;
- }
@ApiParam()
- @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
- @RequestMapping(value = "getUser/{id}", method = RequestMethod.GET)
- public User getUser(@ApiParam(naeme = "id",value = "用户id", required = true) @PathVariable(value = "id") String id) {
- return new User(id, "itguang", "123456");
- }//@ApiParam这个注解,需要注意的是,这个注解方法的参数前面,不能直接用在方法上面.
@ApiImplicitParams()、@ApiImplicitparam()
- ···
- @Api("测试用例1")
- @Controller
- public class swaggerTestUse(){
- @ApiOperation(value = "apiOperationSwaggerTest", notes = "apiOperationSwagger测试")
- @ApiImplicitParams({@ApiImplicitParam(name = "id", value = "id入参", required = true, dataType = "Integer", paramType = "query"),
- @ApiImplicitParam(name = "brand", value = "brand", required = true, dataType = "BRAND", paramType = "body")
- })
- public void apiOperationSwaggerTest(Integer id, Brand band){
- }
- }
以上就是SpringBoot整合Swagger2的步骤详解的详细内容,更多关于SpringBoot整合Swagger2的资料请关注服务器之家其它相关文章!
原文链接:https://www.cnblogs.com/yrxing/p/14651341.html