Integrated use of Springfox and swagger (17)

First, preface

Let's take a look at the relationship between Springfox and swagger first.

Swaggerapi development framework, this framework with "open api Declaration "(OPENAPI specification ,oas) based on the entire The development cycle of span style= "Font-family:calibri" >api

Oasapi Specification, which is used to describe a complete set of api interface, including an interface that is getPOST request Ah, what are the parameters which header Ah, Will be included in this file. It is usually designed to be yamljson

because Spring Marty pitt wrote a spring swagger-springmvc swagger integrated into the Span style= "Font-family:calibri" >springmvcspringfoxspringfoxspringfox-swagger2

Pringfox-swagger2 is still dependent on the OSA specification document, which is a JSON file that describes the API , and the function of this component is to help us automatically generate this JSON file , the other component that we'll be using springfox-swagger-ui is to parse the JSON file and present it in a more friendly way.

This is the introduction, we simply introduce the configuration of Springfox-swagger2, to help you to achieve the smooth use of the text, there are many of their own understanding, if there are errors, welcome criticism.

Ii. description of the configuration process

Before we start coding, we have a general understanding of the configuration process.

In the preface, we know that our first task is to generate a style= font-family that satisfies the Osajson file (of course, create a spring< Span style= "font-family: The song Body" of the project will not say). For this task, springfoxdocket (abstract meaning) class, we need to make it into a bean injected into Obviously, we need a configuration file, and in a way (obviously it will be an annotation) tells the program that this is a swagger configuration file.

a Osa The canonical document needs a lot of information to describe this api, Springfox allows us to synthesize the information group into a apiinfodocket (of course, you can not construct this class , and directly use null but your this api low< Span style= "font-family: Song Body" >).

Next, we're going to write the controller, of course it doesn't matter, not Springfox You still have to write the controller, it's important to tell springfox, this controller is a need for him to collect api The controller of information, needless to say, this will still be annotated way, at the same time, we to the configuration file and controller together, You need to indicate in the configuration file where to gather information about the controller that may be api

here, generate Osa canonical Json The configuration of the file is over. Although the build process is more complex than I described, these programs will help us complete, and we can style= "Font-family:calibri" through similar http://localhost:8080/demo/v2/api-docs< span style= the path to "font-family: Song body" To view this json file. This v2/api-docsspringfox The default path of the generated document.

Next, we need to visualize it, if we use SWAGGER-SPRINGMVC, we need to download a Swagger UI Display page, and change the path to the above HTTP/ Localhost:8080/demo/v2/api-docs, here you can feel that theswagger UI is parsing a json file. You can still do this, but Springfox provides a Springfox-swagger-ui component that does not need to be configured, and we only need to introduce this dependent component to see the final effect, and this route will be http://localhost:8080/demo/swagger-ui.html.

Iii. Introduction of dependency

If I write well, believe to see here, you have a general understanding of the use of Springfox swagger2 flow. Well, let's go into the first step of formal coding: introducing dependencies.

Here we use Maven to introduce dependency, you can go to http://mvnrepository.com search springfox, you can see springfox Swagger2 and Springfox Swagger The Ui, then you can get the latest resources from it. As follows:

<Dependency><GroupId>io.springfox</GroupId><Artifactid>springfox-swagger2</Artifactid><Version>2.7.0</Version></Dependency><dependency> <groupid>io.springfox</< Span style= "COLOR: #800000" >groupid> <artifactid>springfox-swagger-ui </artifactid> < version>2.7.0</< Span style= "COLOR: #800000" >version></dependency>         

Also requires a dependent component:

<Dependency> <groupId>com.fasterxml.jackson.core</groupId> <  Artifactid>jackson-databind</artifactid> <version>2.6.6  </version></dependency>        

四、一个 a simple configuration file

In order to be clear, we can first build a config directory in the common source package , and create a swaggerconfig.java file in it, which is a spring configuration file, so the location and file name have little impact.

First on the code (refer to the blog http://blog.csdn.net/u012476983/article/details/54090423 here):

@Configuration//Must exist @enableswagger2//Must exist @enablewebmvc//Must exist @componentscan (Basepackages = {"Com.xiaoming.SpringMVC.controller"})//Scan API Controller Package name must be present can also scan class directly (basepackageclasses)Publicclass swaggerconfig{@Bean public docket Customdocket () { return new docket ( documentationtype.swagger_2). Apiinfo (Apiinfo ()); } private Apiinfo Apiinfo () {Contact contact = new Contact" ("Xiaoming", "http://www.cnblogs.com/getupmorning/", "[email protected]" ); return new Apiinfobuilder (). Title ("Foreground API Interface"        

As you are sure to use the IDE, you do not write all kinds of import .

First of all, this Swaggerconfig class has four annotations, see the name to understand what it means. Among them,@Configuration,@EnableWebMvc and @ComponentScan are Spring annotations, and @EnableSwagger2 is used to start Swagger support, which indicates that this is a Spring Swagger configuration file.

After that, a bean is definedMethodCustomdocket，SpringThe name doesn't matter, it's important to return aDocketClassDocumentationtype.swagger_2as a parameter of the docket construction method, the Swagger version 2.0 is specified, and the 3.0 version is already being announced on the official website . The subsequent apiinfo is to invoke the next apiinfo function to create the docket information. The apiinfo function uses apiinfobuilder to create the Apiinfo class.

How far Controller

In fact, the controller does not need to be configured, it will already be recognized by the Springfox Swagger , but here we symbolically add a descriptive message:

@Controller @requestmapping ("/test")class TestController {    @ApiOperation (value= "a test API", notes = " The first Test API ") @ResponseBody @RequestMapping (value ="/hello ", method =publicreturn" Hello ";}}  

There is only one more @apioperation annotation, and the other is exactly the same as a normal SPRINGMVC controller.

In fact, in order to form a complete API document, you need to add a lot of annotations, if it is written in the same file will appear bloated, we often write an interface file, the annotations are placed in the interface file, and then use an entity class to implement the Controller, is the implementation of configuration and logical separation.

Vi. viewing interface files and documents

If there is no problem, you can now deploy the project and open Http://localhost:8080/demo/v2/api-docs:

Firefox provides a plugin to view JSON, we recommend that you try it.

Needless to say, there is a lot of information that you can see before you configure it. Inject description,version,title, etc. And it does have TestController information.

Finally, we open the http://localhost:8080/swagger-ui.html, we can see a beautiful interface:

Integrated use of Springfox and swagger (17)