文档章节

Swagger Integration

c
 chensanti234
发布于 2016/04/26 15:35
字数 724
阅读 37
收藏 0

This wiki writes down the integration between spring-boot and Swagger. Swagger is a powerful restful API framework. It can discover and generate documentation for rest API by using the annotation at code level. This makes the documentation always synchronized with the actual API.

For more of Swagger's capability, please refer to: http://swagger.io

Setup

Here are the steps to set up your spring-boot application to use Swagger. Assume maven is used. 


  1. Add below dependencies to your POM.

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

    Swagger does not support spring-boot officially. The support comes from a third-party project springfox.  Here is the official site of springfox: http://springfox.github.io/springfox/


  2. In your main application, add swagger support by simply adding an annotation "@EnableSwagger2"

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


    That's all the magic! restart the spring-boot application and visit in your browser: http://localhost:8090/v2/api-docs
    You will see all the restful API returned as a JSON. But that's not so friendly. 

  3. Using the swagger UI.

    NOTE: springfox docket is another option if you just want to use the default swagger ui. And It's not possible to use both options.

    Clone the project from https://github.com/swagger-api/swagger-ui and put the "dist" folder to src/main/resources/static and rename it to "swagger". Reboot the application and then visit: http://localhost:8090/swagger/index.html
    You will see all the registered APIs in your application.


    By default, swagger will generate the link text and description based on you controller's name. For example, "JobController" will be shown as "job-controller" and "Job Controller". 

    You can customize the display text in your code by using annotation, which will be covered in next section.

    You can also customize the UI code.

  4. Using Springfox Docket

    Springfox Docket is another option to show the service UI. Just declare a Docket using "@Bean" as shown below. Note if you are using docket, you got convenience by sacrificing the customizability.

    @SpringBootApplication
    @EnableAutoConfiguration(exclude = {HypermediaAutoConfiguration.class})
    @EnableSwagger2
    public class Application {
    
        public static void main(String[] args) throws Exception {
            SpringApplication.run(Application.class, args);
        }
    
        @Bean
        public Docket newsApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("Process Solution")
                    .apiInfo(apiInfo())
                    .select()
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Cfl Rest API")
                    .description("Powered By Spring Boot")
                    .build();
        }
    }


    And then visit: http://localhost:8090/swagger-ui.html

    For details, please refer to http://springfox.github.io/springfox/docs/current

Swagger annotations

The springfox is smart to generate the documentation by parsing the spring rest service declaration. Most of the time, this is enough. You just need to name your class and method in a meaningful way. But sometimes if you want to generate more detailed information, you can leverage the swagger annotation.

This wiki will only list the typical annotations, for full details please refer to: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#api

  1. "@Api"From Swagger 2.0, this annotation is used to declared all the operations under the class.
  2. "@ApiOperation"
    This is used to document a rest method.
  3. "@ApiParam"
    This is used to document a parameter in a method.
  4. "@ApiModel"
    This is used to document the model(a java bean) that will be shown in swagger UI.


Here is a sample restful service with swagger:


@RestController
@RequestMapping("/job")
@Api(value = "Spark Job Controller", produces = "application/json", basePath = "/job",
authorizations = {
        @Authorization(value = "sample auth")
}, tags = {"spark","job"})
public class JobController {

    @Autowired
    private JobService jobService;

    @RequestMapping(value = "/all", method = RequestMethod.GET)
    @ApiOperation(value = "Get all running jobs", notes = "this includes spark standalone jobs as well as yarn jobs")
    public Set<Job> all() {
        return jobService.getAllJobs();
    }

    @RequestMapping(method = RequestMethod.PUT)
    public Job add(@RequestBody Job job) {
        return jobService.save(job);
    }

    @RequestMapping(method = RequestMethod.POST)
    public Job update(@RequestBody Job job) {
        return jobService.save(job);
    }

    @RequestMapping(value = "/{jobId:.+}", method = RequestMethod.DELETE)
    @ResponseStatus(HttpStatus.OK)
    public void delete(
            @ApiParam(value = "Spark job id", required = true)
            @PathVariable("jobId") String jobId) {
        jobService.delete(jobId);
    }

    @MessageMapping("/job/start")
    public void start(Job job) throws InterruptedException {
        jobService.start(job);
    }
}
 
 


Declare a model API to be inspected by swagger

Here shows the net effect:

© 著作权归作者所有

c
粉丝 0
博文 35
码字总数 9512
作品 0
深圳
私信 提问
加载中

评论(0)

聊聊dubbo的DubboSwaggerService

序 本文主要研究一下dubbo的DubboSwaggerService DubboSwaggerService dubbo-2.7.2/dubbo-rpc/dubbo-rpc-rest/src/main/java/org/apache/dubbo/rpc/protocol/rest/integration/swagger/Dubbo......

go4it
2019/07/06
75
0
How to Write a Spring Boot Web Maven Archetype With Common Practices in Place

Here we are sharing a custom Spring Boot web Maven archetype I have created to encapsulate all the common practices, as an example how you can do the same in your team for commo......

Mahmoud Romeh
2017/12/07
0
0
Spring Integration整合Swagger2 有哪位做过吗,我的Swagger-ui.html访问不到

Spring Integration整合Swagger2 有哪位做过吗,我的Swagger-ui.html访问不到,会被认为是不存在的url

hehaheha
2019/07/02
239
0
Springfox 2.6.0 发布,开源的 API doc 框架

Springfox 2.6.0 发布了,Springfox的前身是swagger-springmvc,是一个开源的API doc框架,可以将我们的Controller的方法以文档的形式展现。 改进内容: (#1498) Add pathsGroupedBy configu...

淡漠悠然
2016/10/09
3K
10
swagger-codegen生成java客户端代码

前后端分离的时候,需要建立契约,Swagger可达到该目的(略)。 建立Rest接口后,通过swagger-codegen项目可以自动生成对应的客户端代码(c++、php、java、js、node等等), 关于swagger-cod...

tyou
2018/09/29
844
0

没有更多内容

加载失败,请刷新页面

加载更多

Java基本程序设计结构

简述 Java起源于Sun公司为机顶盒开发的一款开发语言“Oak”,由于该名称被抢注更名为“Java”。Java是基于面向对象的开发语言,其特性在于“一次编译,到处运行”,这实现依赖于JVM。 Java程...

Yongy
23分钟前
49
0
【jquery仿dataList——性能优化】模板预编译思想提高性能10倍以上!!!

那撒,IE和google性能不减反增,求高手解释....... 前言 呵呵,当然,什么预编译什么性能提高5倍以上基本上市坑爹的,这里就是为了吸引阅读量,哈哈。 上当的大哥主动顶下哇??? 正题 之前...

shzwork
27分钟前
57
0
用博客系统开发作文网站探索MYSQL数据库性能和缓存技巧[图]

用博客系统开发作文网站探索MYSQL数据库性能和缓存技巧[图] 最近忙着建站,感觉现在建站是越来越难了,但还是用ZBLOG系统建了一个作文网站,叫做求索作文网,但是发现博客系统的缺点也还是有...

原创小博客
30分钟前
31
0
LinearLayout不在ScrollView内扩展

我在ScrollView中有一个LinearLayout ,它有android:layout_height="fill_parent" ,但它没有扩展到ScrollView的整个高度。 我的布局看起来像: level layout layout_width layout_......

技术盛宴
48分钟前
37
0
docker上启动nginx,并配置修改nginx的配置文件

1.使用docker 下载nginx 镜像 docker pull nginx 2.启动nginx docker run --name nginx -p 80:80 -d nginx 这样就简单的把nginx启动了,但是我们想要改变配置文件nginx.conf ,进入容器,命令...

yuxw
52分钟前
45
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部