首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >spring boot集成swagger构建API文档

spring boot集成swagger构建API文档

作者头像
田维常
发布2019-07-16 10:10:00
5940
发布2019-07-16 10:10:00
举报

使用swagger不用手工写API相关的word文档了,并且还可以使用swagger生成的API文档进行测试,使用起来倍儿爽。接下来咱们就来搞一个demo案例。

先是pom.xml引用和版本:

  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.8.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <groupId>com.lawt</groupId>
  <artifactId>swagger-demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>swagger-demo</name>
  <description>Demo project for Spring Boot</description>

  <properties>
    <java.version>1.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <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>
  </dependencies>

springboot启动类:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication {
  public static void main(String[] args) {
    SpringApplication.run(SwaggerDemoApplication.class, args);
  }
}

swagger相关扫描和配置:

import org.springframework.beans.factory.annotation.Value;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
   //扫描路径
    private final String SWAGGER_SCAN_BASE_PACKAGE
     = "com.lawt.swaggerdemo.controller";
    //开关
    @Value("${swagger.enable}")
    private Boolean enable;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enable)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的swagger demo API")
                .version("1.0.0")
                .build();
    }
}

一个controller类:

import com.lawt.swaggerdemo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(description = "用户信息操作")
public class UserController {
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable("id") Integer id) {
        return new User(10001, "lawt");
    }
}

实体类User:

import io.swagger.annotations.ApiModelProperty;
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer userId;
    @ApiModelProperty(value = "用户名称")
    private String userName;

    public User(Integer userId, String userName) {
        this.userId = userId;
        this.userName = userName;
    }
   //get set method .....
}

配置项:

server.port=8801
#如果线上环境不需要swagger功能,需要改成false
swagger.enable=true

启动,并访问:

http://127.0.0.1:8801/swagger-ui.html

页面显示:

点击 Show/Hide

点击右边的 获取用户详细信息

输入参数

点Try it out!

显示 linux环境下怎么请求改接口,请求参数、返回参数等信息。

Ok,自此demo已经搞定,swagger远不止这些功能。

可以参考:

官网:https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview 其他参考网址: https://blog.csdn.net/u014231523/article/details/76522486

本文参与 腾讯云自媒体分享计划,分享自微信公众号。
原始发表:2019-06-12,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 Java后端技术栈 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体分享计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档