Swagger Integration

最新推荐文章于 2024-07-09 21:02:55 发布

weixin_33874713

最新推荐文章于 2024-07-09 21:02:55 发布

阅读量116

点赞数

文章标签：大数据 ui json

原文链接：https://my.oschina.net/chensanti234/blog/666495

版权

2019独角兽企业重金招聘Python工程师标准>>>

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.

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/

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.
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.

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

"@Api"From Swagger 2.0, this annotation is used to declared all the operations under the class.
"@ApiOperation"
This is used to document a rest method.
"@ApiParam"
This is used to document a parameter in a method.
"@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