springboot 配置使用swagger2操作

springboot 配置使用swagger2操作

swagger是一个功能强大的在线API文档的框架，提供了优雅的API在线文档的查阅和测试功能。

利用swagger2可以很方便的构建RESTful风格的API文档，在springboot中使用也非常方便，主要是在controller前配置添加注解就可以了，详细配置过程如下：

1. maven依赖包

使用目前最新版本为例，pom.xml添加的代码如下

io.springfox

springfox-swagger-ui

2.9.2

io.springfox

springfox-swagger2

2.9.2

2. 配置类的编写

配置类的编写同样非常简单，可以直接复制粘贴以下代码，但是一定要注意做适当修改，尤其是设置basePackage的路径，一定要根据实际情况修改。

新建一个config文件夹，在此文件夹中新建一个类

package cn.smileyan.swagger.config;

import org.springframework.beans.factory.annotation.Configurable;

import org.springframework.context.annotation.Bean;

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;

@EnableSwagger2

@Configurable

public class Swagger2 {

/**

* 特别要注意.apis(RequestHandlerSelectors.basePackage("cn.smileyan.swagger.controller"))

* 此中的cn.smileyan.swagger.controller一定要修改为自己controller包。

* @return

*/

@Bean

public Docket createRestApi() {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo())

.select()

.apis(RequestHandlerSelectors.basePackage("cn.smileyan.swagger.controller"))

.paths(PathSelectors.any())

.build();

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder().title("springboot使用swagger例子")

.description("简单优雅的restful风格")

.termsOfServiceUrl("https://smileyan.cn")

.version("1.0")

.build();

}

}

不能忘记类前面的@EnableSwagger2 与 @Configurable配置注解。以及后面的@Bean注解。

3. @EnableSwagger2 不能忘了

除了这个位置需要添加这个注解，还有springboot的运行类(application类）也要添加这个注释，否则会出现错误。

如图所示，我的application类名为SwaggerApplication，在这个类上面添加@EnableSwagger2

package cn.smileyan.swagger;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication

@EnableSwagger2

public class SwaggerApplication {

public static void main(String[] args) {

SpringApplication.run(SwaggerApplication.class, args);

}

}

4. 编写controller类，添加注解，注意这个controller路径与上面配置类的路径要保持一致。

package cn.smileyan.swagger.controller;

import io.swagger.annotations.ApiOperation;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RequestMethod;

import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;

import java.util.Map;

@RestController

@RequestMapping("/user")

public class UserController {

@ApiOperation(value = "用户测试",notes = "贵宾用户")

@RequestMapping(value = "",method = RequestMethod.GET)

private Map getUser() {

Map map = new HashMap<>(1);

map.put("result","success");

return map;

}

}

5. http://运行，打开api文档http://localhost:8080/swagger-ui.html

效果如下：

可以点开user-controller，效果如下：

完成测试。很简单吧。

常用注解

@Api ： 修饰整个类，用于描述Controller类

@ApiOperation：描述类的方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应的一个描述

@ApiResponses：HTTP响应的整体描述

@ApiIgnore：使用该注解，表示Swagger2忽略这个API

@ApiError：发生错误返回的信息

@ApiParamImplicit：一个请求参数

@ApiParamsImplicit：多个请求参数

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。