springboot(十六)-swagger2

末蓝、 2021-11-05 02:40 448阅读 0赞

## [SpringBoot整合Swagger2][SpringBoot_Swagger2] ##

相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。

手写Api文档的几个痛点：

1.  文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2.  接口返回结果不明确
3.  不能直接在线测试接口，通常需要使用工具，比如postman
4.  接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

### 添加pom依赖 ###

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.6.1</version>
    </dependency>
    
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.6.1</version>
    </dependency>

### Swagger配置类 ###

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

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.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /**
     * @author zh
     * @ClassName cn.saytime.Swgger2
     * @Description
     * @date 2017-07-10 22:12:31
     */
    @Configuration
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("springboot利用swagger构建api文档")
                    .description("简单优雅的restfull风格，https://www.cnblogs.com/fengyuduke")
                    .termsOfServiceUrl("https://www.cnblogs.com/fengyuduke")
                    .version("1.0")
                    .build();
        }
    }

> 用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

### 启动类 ###

@SpringBootApplication
    @EnableSwagger2
    public class SpringbootSwagger2Application {
    
        public static void main(String[] args) {
            SpringApplication.run(SpringbootSwagger2Application.class, args);
        }
    }

加上注解@EnableSwagger2 表示开启Swagger。

import cn.saytime.bean.JsonResult;
    import cn.saytime.bean.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.http.ResponseEntity;
    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 springfox.documentation.annotations.ApiIgnore;
    
    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    
    /**
     * @author zh
     * @ClassName cn.saytime.web.UserController
     * @Description
     */
    @RestController
    public class UserController {
    
        // 创建线程安全的Map
        static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
    
        /**
         * 根据ID查询用户
         * @param id
         * @return
         */
        @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
        @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
        public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
            JsonResult r = new JsonResult();
            try {
                User user = users.get(id);
                r.setResult(user);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 查询用户列表
         * @return
         */
        @ApiOperation(value="获取用户列表", notes="获取用户列表")
        @RequestMapping(value = "users", method = RequestMethod.GET)
        public ResponseEntity<JsonResult> getUserList (){
            JsonResult r = new JsonResult();
            try {
                List<User> userList = new ArrayList<User>(users.values());
                r.setResult(userList);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 添加用户
         * @param user
         * @return
         */
        @ApiOperation(value="创建用户", notes="根据User对象创建用户")
        @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        @RequestMapping(value = "user", method = RequestMethod.POST)
        public ResponseEntity<JsonResult> add (@RequestBody User user){
            JsonResult r = new JsonResult();
            try {
                users.put(user.getId(), user);
                r.setResult(user.getId());
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 根据id删除用户
         * @param id
         * @return
         */
        @ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
        @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
        public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
            JsonResult r = new JsonResult();
            try {
                users.remove(id);
                r.setResult(id);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        /**
         * 根据id修改用户信息
         * @param user
         * @return
         */
        @ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
                @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
        })
        @RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
        public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
            JsonResult r = new JsonResult();
            try {
                User u = users.get(id);
                u.setUsername(user.getUsername());
                u.setAge(user.getAge());
                users.put(id, u);
                r.setResult(u);
                r.setStatus("ok");
            } catch (Exception e) {
                r.setResult(e.getClass().getName() + ":" + e.getMessage());
                r.setStatus("error");
    
                e.printStackTrace();
            }
            return ResponseEntity.ok(r);
        }
    
        @ApiIgnore//使用该注解忽略这个API
        @RequestMapping(value = "/hi", method = RequestMethod.GET)
        public String  jsonTest() {
            return " hi you!";
        }
    }

启动SpringBoot项目，访问 [http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

![1604432-20190515160808383-1686152364.png][]

### Swagger注解 ###

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

*  @Api：修饰整个类，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数

转载于:https://www.cnblogs.com/fengyuduke/p/10870099.html

[SpringBoot_Swagger2]: https://www.cnblogs.com/jtlgb/p/8532433.html
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[1604432-20190515160808383-1686152364.png]: /images/20211104/702e924139724e74a159c35d8474329e.png