16springcloud整合Swagger2构建Restful服务的APIs

70次阅读

共计 8344 个字符，预计需要花费 21 分钟才能阅读完成。

公众号：java 乐园

Spring Cloud 将服务注册到了 Eureka 上，可以从 Eureka 的 UI 界面中，看到有哪些服务已经注册到了 Eureka Server 上；但是如果想查看当前服务提供了哪些 RESTful 接口方法的话，就无法从 Eureka Server 获取了，而传统的方法是梳理一个接口文档来供开发人员之间来进行交流。这种情况下经常会造成文档和代码的不一致性，比如说代码改了，但是接口文档还没来得及修改等问题，而 Swagger2 则给我们提供了一套完美的解决方案，下面来看看 Swagger2 是如何来解决这个问题的。

1、新建项目 sc-swagger2，对应的 pom.xml 文件

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>spring-cloud</groupId>
    <artifactId>sc-swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>sc-swagger2</name>
    <url>http://maven.apache.org</url>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.4.RELEASE</version>
    </parent>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Finchley.RELEASE</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

        </dependencies>
    </dependencyManagement>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

2、新建 springboot 启动类

package sc.swagger2;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

}

3、新建 Swagger2 配置类

package sc.swagger2.config;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("sc.swagger2"))
                .paths(PathSelectors.any())
                .build();}

    private ApiInfo apiInfo() {return new ApiInfoBuilder()
                .title("Spring Boot 中使用 Swagger2 构建 RESTful APIs")
                .description("更多 Spring Boot 相关文章请关注: JAVA 乐园  公众号")
                .termsOfServiceUrl("https://edu.csdn.net/lecturer/995")
                .contact(new Contact("huangjinjin", //
                        "https://edu.csdn.net/lecturer/995",//
                        "happyhuangjinjin@sina.com"))
                .version("1.0")
                .build();}


}

4、新建一个模拟的 Controller

package sc.swagger2.controller;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import sc.swagger2.model.User;

@Api(value="用户管理")
@Controller
public class UserController {@ApiResponses({ @ApiResponse(code = 000000, message = "操作成功"),
        @ApiResponse(code = 000001, message = "服务器内部异常") })
    @GetMapping(value = "/feign/user/getUser/{id}")
    @ResponseBody
    @ApiOperation(value = "获取根据 Id 用户信息",response = User.class)
    @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long",example="100")
    public Map<String, Object> getUser(@PathVariable Long id) {Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        User u = new User();
        u.setId(1L);
        u.setAge(23);
        u.setUserName("huangjinjin");
        u.setPosition("cto");
        result.put("body", u);
        return result;
    }

    @ApiResponses({@ApiResponse(code = 000000, message = "操作成功"), 
        @ApiResponse(code = 000001, message = "服务器内部异常") })
    @RequestMapping(value = "/feign/user/listUser", method = RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value = "获取用户列表")
    public Map<String, Object> listUser() {Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        User u = new User();
        u.setId(1L);
        u.setAge(23);
        u.setUserName("huangjinjin");
        u.setPosition("cto");
        List<User> list = new ArrayList<User>();
        list.add(u);
        result.put("body", list);
        return result;
    }

    @ApiResponses({@ApiResponse(code = 000000, message = "操作成功"), 
        @ApiResponse(code = 000001, message = "服务器内部异常") })
    @PostMapping(value = "/feign/user/addUser")
    @ResponseBody
    @ApiOperation(value = "添加用户", notes = "根据 User 对象创建用户")
    @ApiImplicitParams({@ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
        @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "String"),
        @ApiImplicitParam(name = "position", value = "职位", required = true, dataType = "String"),
        @ApiImplicitParam(name = "id", value = "用户 ID", required = false, dataType = "Long",example="100")})
    public Map<String, Object> addUser(User user) {Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        result.put("body", 1);
        return result;
    }

    @ApiResponses({@ApiResponse(code = 000000, message = "操作成功"), 
        @ApiResponse(code = 000001, message = "服务器内部异常") })
    @ApiOperation(value = "更新用户")
    @PutMapping(value = "/feign/user/updateUser")
    @ResponseBody
    @ApiImplicitParams({@ApiImplicitParam(name = "userName", value = "用户名", required = true, dataType = "String"),
        @ApiImplicitParam(name = "age", value = "年龄", required = true, dataType = "String"),
        @ApiImplicitParam(name = "position", value = "职位", required = true, dataType = "String"),
        @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long", example="100")})
    public Map<String, Object> updateUser(User user) {Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        result.put("body", 1);
        return result;
    }

    @ApiResponses({@ApiResponse(code = 000000, message = "操作成功"), 
        @ApiResponse(code = 000001, message = "服务器内部异常") })
    @DeleteMapping(value = "/feign/user/deleteUser/{id}")
    @ResponseBody
    @ApiOperation(value = "删除用户")
    @ApiImplicitParam(name = "id", value = "用户 ID", required = true, dataType = "Long",example="100")
    public Map<String, Object> deleteUser(@PathVariable Long id) {Map<String, Object> result = new HashMap<String, Object>();
        result.put("code", "000000");
        result.put("msg", "success");
        result.put("body", 1);
        return result;
    }
    
}

5、新建 User 模型类

package sc.swagger2.model;

import java.io.Serializable;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel
public class User implements Serializable {

    private static final long serialVersionUID = 4639927446947303736L;

    @ApiModelProperty(name="id", dataType="Long", value="主键 ID")
    private Long id;

    @ApiModelProperty(name="userName", dataType="String", value="姓名", required=true)
    private String userName;

    @ApiModelProperty(name="age", dataType="String", value="年龄", required=true)
    private Integer age;

    @ApiModelProperty(name="position", dataType="String", value="职位")
    private String position;

    public String getUserName() {return userName;}

    public void setUserName(String userName) {this.userName = userName;}

    public Integer getAge() {return age;}

    public void setAge(Integer age) {this.age = age;}

    public String getPosition() {return position;}

    public void setPosition(String position) {this.position = position;}

    public Long getId() {return id;}

    public void setId(Long id) {this.id = id;}

}

6、启动 sc-swagger2 项目，并验证是否启动成功
方式一：查看日志

方式二：访问地址
http://127.0.0.1:9092/swagger-ui.html

或者访问 http://localhost:9092/v2/api-docs

7、在界面 http://127.0.0.1:9092/swagger-ui.html 点击【user-controller】可以看到所有的接口，同时也可以在界面上进行接口调用调试

正文完
spring
发表至： java
2019-09-07
 0
关于云原生:基于-RocketMQ-Prometheus-Exporter-打造定制化-DevOps-平台
关于java:三Spring5x-与日志框架的整合与属性注入
java bean 对象属性复制框架BeanMapping-release_0.0.2-注解支持
常见的集合容器应当避免的坑