57.java项目-activiti实战项目(3)--swagger

最新推荐文章于 2021-02-10 11:09:23 发布

leokk111

最新推荐文章于 2021-02-10 11:09:23 发布

阅读量532

点赞数 1

分类专栏： ihrm项目 javaEE

本文链接：https://blog.csdn.net/weixin_45449911/article/details/105726994

版权

javaEE 同时被 2 个专栏收录

50 篇文章 0 订阅

订阅专栏

ihrm项目

15 篇文章 0 订阅

订阅专栏

swagger

1.概况

Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。
Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。
Swagger 是一种通用的，和编程语言无关的 API 描述规范。

2.应用场景

分为两类：
第一：先定swagger接口文档，后开发后端程序
如果你的 RESTful API 接口都开发完成了，你可以用 Swagger-editor 来编写 API 文档（ yaml 文件或 json 文件），然后通过 Swagger-ui 来渲染该文件，以非常美观的形式将你的 API 文档，展现给你的团队或者客户。
第二：先开发，后使用swagger来生成接口文档
如果你的 RESTful API 还未开始，也可以使用 Swagger ，来设计和规范你的 API，以 Annotation （注解）的方式给你的源代码添加额外的数据。这样，Swagger 就可以检测到这些数据，自动生成对应的 API 文档。

3.开发步骤

(1)导入依赖

	<!--这里是swagger的依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
   <!--这里主要是前端页面的依赖,也就是swagger-ui的依赖-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

(2)配置本API的信息
主要包括两类:
1.必要信息:本api的扫描路劲,加载方式等
2.描述信息:本API的作者,标题,版本等

package com.gl.swagger.config;

import lombok.Data;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;

/**
 * @ClassName SwaggerConfig
 * @Author gl
 * @Date 2020/3/4 23:17
 * @Description
 * 本类是用来加载swagger的配置
 * 主要配置有就几个:
 * 1.描述信息:本api的基本信息,包括标题等.
 * 2.配置信息:配置swagger的包扫描,加载方式
 */
@EnableSwagger2  //启动swagger
@Configuration  //将本类注入spring容器
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())  //加载本api的基本信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.gl.swagger.controller"))  //扫描的映射controller层
                .paths(PathSelectors.any()) // 路径使用any风格
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs") //标题
                .description("测试swagger") //描述
                .termsOfServiceUrl("localhost:8080/test")  //链接
                .contact("gl测试") //无
                .version("1.0") //版本
                .build();
    }
}

(3)在具体的Controller类中的方法上加注解

主要注解:
@Api(value = “用户表的操作”) 加载类上,描述类的作用
@ApiOperation(value=“获取用户列表”, notes="") : 描述接口的作用
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true,
dataType = “Long”) 描述接口的参数
@ApiImplicitParams({
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”),
@ApiImplicitParam(name = “user”, value = “用户详细实体user”, required = true, dataType = “User”)
}) 多个参数

package com.gl.swagger.controller;

import com.gl.swagger.pojo.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@Api(value = "用户表的操作")
@RestController
@RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下，可去除
public class UserController {

    static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

    /**
     * 获取用户列表
     * @return
     */
    @ApiOperation(value="获取用户列表", notes="")  //描述本接口用途
    @RequestMapping(value={""}, method= RequestMethod.GET)
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    /**
     * 创建用户
     * @param user
     * @return
     */
    @ApiOperation(value="创建用户", notes="根据User对象创建用户")  //描述本接口的作用
    //描述本接口的参数: name-参数名  value-参数描述  required-是否必须 dataType-参数类型
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    @RequestMapping(value="", method=RequestMethod.POST)
    public String postUser(@RequestBody User user) {
        users.put(user.getId(), user);
        return "postUser";
    }


    /**
     * 获取用户详细信息
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息") //描述本接口的作用
    //描述本接口的参数: name-参数名  value-参数描述  required-是否必须 dataType-参数类型
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.GET)
    public User getUser(@PathVariable Long id) {
        return users.get(id);
    }

    /**
     * 更新用户信息
     * @param id
     * @param user
     * @return
     */
    //描述本接口的作用
    @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象，并根据传过来的user信息来更新用户详细信息")
    //多个参数
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value="/{id}", method=RequestMethod.PUT)
    public String putUser(@PathVariable Long id, @RequestBody User user) {
        User u = users.get(id);
        u.setName(user.getName());
        u.setAge(user.getAge());
        users.put(id, u);
        return "putUser";
    }

    /**
     * 删除用户
     * @param id
     * @return
     */
    //描述本接口的作用
    @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
    //描述本接口的参数: name-参数名  value-参数描述  required-是否必须 dataType-参数类型
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable Long id) {
        users.remove(id);
        return "deleteUser";
    }

}

(4) 正常来说，配置以上三步就可以了，但如果配置静态资源拦截，则需要配置静态资源放行

/**
 * <p>
 *     此配置类可配置拦截器、参数解析器、返回值解析器、跨域支持等等
 * </p>
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private AuthorizationInterceptor authorizationInterceptor;
    @Autowired
    private LoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver;

    /**
     *  如果配置跨域，就增加这个配置
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("/static/");
        registry.addResourceHandler("/js/**").addResourceLocations("/js/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");
    }

    /**
     * 拦截器配置
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**");
    }

    /**
     * 跨域支持配置
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600);
    }

    /**
     * 参数解析配置
     * @param resolvers
     */
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(loginUserHandlerMethodArgumentResolver);
    }
}

(5) 至此基本配置已完成，访问 localhost:8080/swagger-ui.html
显示如下图:
在这里插入图片描述

4.主要API讲解

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

leokk111

关注

1
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
57.java项目-activiti实战项目(3)--swagger

swagger1.概况Swagger 是最流行的 API 开发工具，它遵循 OpenAPI Specification（OpenAPI 规范，也简称 OAS）。Swagger 可以贯穿于整个 API 生态，如 API 的设计、编写 API 文档、测试和部署。Swagger 是一种通用的，和编程语言无关的 API 描述规范。2.应用场景如果你的 RESTful API 接口都开发完成了，...
复制链接

扫一扫