Spring Boot集成Swagger设计RESTFul APIs

最新推荐文章于 2023-09-07 14:58:22 发布

AE86-打破常规

最新推荐文章于 2023-09-07 14:58:22 发布

阅读量278

点赞数

分类专栏： Spring Boot 文章标签： Spring Boot整合swagger设计RESTFul swagger

本文链接：https://blog.csdn.net/weixin_40936211/article/details/89458458

版权

Spring Boot 专栏收录该内容

15 篇文章 0 订阅

订阅专栏

基本概述

本文记载了Spring Boot+Spring Fox的方式整合Swagger框架

Swagger

The Best APIs are Built with Swagger Tools | Swagger--最好的API是用Swagger工具构建的，显然，Swagger是一个规范完成的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

官网：https://swagger.io/

Github

HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档: https://github.com/swagger-api/swagger-ui

模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码: https://github.com/swagger-api/swagger-codegen

Swagger API 编辑器：https://github.com/swagger-api/swagger-editor

swagger注释API详细说明：https://blog.csdn.net/xupeng874395012/article/details/68946676

swagger常用注解说明：https://blog.csdn.net/u014231523/article/details/76522486

精心设计的API的特征

通常，有效的API设计将具有以下特征：

易于阅读和使用：设计良好的API易于使用，其资源和相关操作可以由持续使用它的开发人员快速记忆。
难以滥用：实现和集成具有良好设计的API将是一个简单的过程，编写错误的代码将不太可能产生结果。它具有信息反馈，并且不对API的最终消费者强制执行严格的指导。
完整而简洁：最后，完整的API将使开发人员能够针对您公开的数据制作完整的应用程序。完整性通常会随着时间的推移而发生，大多数API设计人员和开发人员会在现有API的基础上逐步构建。每个拥有API的工程师或公司都必须努力实现这一目标。

swagger常见的注解说明：https://blog.csdn.net/u014231523/article/details/76522486

pom依赖

 <!--swagger -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.8.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.8.0</version>
    </dependency> 
  <!--生成接口文档-->
  <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
  </dependency>

 <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>

            <!--第一步-->
            <!--mvn swagger2markup:convertSwagger2markup-->
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.3.3</version>
                <configuration>
                    <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                    <outputFile>src/docs/asciidoc/generated/v2-api-doc</outputFile>
                    <config>
                        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                    </config>
                </configuration>
            </plugin>

            <!--第二步-->
            <!--mvn asciidoctor:process-asciidoc生成接口文档html页面-->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                    <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <!--目录的位置-->
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

Swagger配置


@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定扫描controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
    /**
     * 项目信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot+Spring Fox的方式整合Swagger设计RESTFul APIs")
                //描述与作者信息
                .description("努力写出优质的代码，而不是仅仅满足于功能上的实现，加油少年！！")
                .contact(new Contact("JackLin","https://mp.csdn.net/postedit","793066408@qq.com"))
                .version("1.0")
                .build();
    }
}

项目结构如下，最后生成的api文档为html或者pdf的格式：

生成HTML API接口文档：

步骤一：

创建实体

@Data
@EqualsAndHashCode(callSuper = true)
@Accessors(chain = true)
@ApiOperation("用户实体")
public class User extends BaseEntity {

    private static final long serialVersionUID = 1L;

    /**
     * 昵称
     */
    @ApiModelProperty(value = "用户名",required = true)    //必填
    @NotBlank(message = "用户名不能为空")
    private String username;

    /**
     * 密码
     */
    @ApiModelProperty(value = "密码")
    @NotBlank(message = "密码不能为空")
    private String password;

    /**
     * 邮件
     */
    @ApiModelProperty(value = "邮箱")
    @Email
    private String email;

    /**
     * 手机电话
     */
    @ApiModelProperty(value = "手机")
    private String mobile;

    /**
     * 性别
     */
    @ApiModelProperty(value = "性别")
    private String gender;

    /**
     * 生日
     */
    @ApiModelProperty(value = "生日")
    private LocalDateTime birthday;

}

步骤二：

创建controller控制器

IndexController

@Api(value = "首页控制器",tags = "首页控制器")
@Controller
public class IndexController extends BaseController{


    @RequestMapping({"","/"})  //如果使用@RequestMapping那么生成的swagger2文档通过GET、HEAD、POST、PUT、DELETE、OPTIONS等方法都可以访问
    public String index(HttpServletRequest request){

        request.setAttribute("author","JackLin");
        return "index";
    }
}

userController

@Api(value = "用户控制器",tags = "用户控制器")
@RestController
@RequestMapping("/user")
public class UserController extends BaseController {

    @Autowired
    private UserService userService;

    @ApiOperation("获取用户列表")
    @GetMapping("")
    public Object getUsers(){
        List<User> users = userService.list();
        return ResponseResult.sussess(users);
    }

    @ApiOperation("根据用户ID查询用户")
    @GetMapping("/{id}")
    public Object getUser(@PathVariable("id") Long id){
        User user = userService.getById(id);
        return ResponseResult.sussess(user);
    }

    @ApiOperation("更新用户")
    @PutMapping("/{id}")
    public Object putUser(@PathVariable Long id,User user){
        User tempUser = userService.getById(id);
        tempUser.setUsername(user.getUsername());
        tempUser.setGender(user.getGender());
        tempUser.setMobile(user.getMobile());

        userService.updateById(tempUser);

        return ResponseResult.sussess(null);
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/{id}")
    public Object deleteUser(@PathVariable("id") Long id){
        userService.removeById(id);
        return ResponseResult.sussess(null);
    }

    @ApiOperation("创建用户")
    @PostMapping("/")
    public Object postUser(@RequestBody User user){
        user.setCreated(new Date());
        user.setGender("男");
        userService.saveOrUpdate(user);
        return ResponseResult.sussess(user);
    }
}

步骤三：

配置swagger2，创建SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定扫描controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo"))
                //指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
    /**
     * 项目信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot+Spring Fox的方式整合Swagger设计RESTFul APIs")
                //描述与作者信息
                .description("努力写出优质的代码，而不是仅仅满足于功能上的实现，加油少年！！")
                .contact(new Contact("JackLin","https://mp.csdn.net/postedit","793066408@qq.com"))
                .version("1.0")
                .build();
    }
}

运行项目，项目启动之后：访问：http://localhost:8080/swagger-ui.html,得到：

接着：

当 BUILD SUCCESS以后，就会在项目的src/docs/asciidoc/目录下生成两个文件夹，分别为generated和html:

到此项目整合完毕。

AE86-打破常规

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
Spring Boot集成Swagger设计RESTFul APIs

基本概述本文记载了Spring Boot+Spring Fox的方式整合Swagger框架SwaggerThe Best APIs are Built with Swagger Tools | Swagger--最好的API是用Swagger工具构建的，显然，Swagger是一个规范完成的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。官网：htt...
复制链接

扫一扫

专栏目录